РАЗДЕЛ
about_CommonParameters
КРАТКОЕ ОПИСАНИЕ
Описание параметров, которые могут использоваться с любым командлетом.
ПОЛНОЕ ОПИСАНИЕ
Общие параметры - это набор параметров командлета, которые могут
использоваться с любым командлетом. Их обработка реализована
разработчиками Windows PowerShell, а не разработчиком командлета,
они автоматически доступны любому командлету.
Общие параметры можно использовать с любым командлетом, но они могут
воздействовать не на все командлеты. Например, если командлет не
генерирует подробные выходные данные, использование параметра Verbose
никак не отразится на его работе.
Некоторые общие параметры переопределяют системные значения по
умолчанию или настройки, установленные с помощью привилегированных
переменных. В отличие от привилегированных переменных общие параметры
воздействуют только на те команды, в которых они используются.
В дополнение к общим параметрам многие командлеты поддерживают
параметры снижения риска WhatIf и Confirm. Эти параметры обычно
поддерживаются командлетами, которые подвергают риску системные
данные или данные пользователя.
Общие параметры перечислены в следующей таблице.
-Verbose
-Debug
-WarningAction
-WarningVariable
-ErrorAction
-ErrorVariable
-OutVariable
-OutBuffer
Параметры снижения риска перечислены в следующей таблице.
-WhatIf
-Confirm
Для получения дополнительной информации о привилегированных переменных
введите следующую команду.
help about_preference_variables
Описания общих параметров
-Verbose[:{$true | $false}]
Отображает подробные сведения о действиях, выполняемых
командой. Эти сведения напоминают сведения в журнале
трассировки или журнале транзакций. Этот параметр будет
работать только с теми командами, которые генерируют подробные
сообщения. Например, этот параметр работает с командой, содержащей
командлет Write-Verbose.
Параметр Verbose переопределяет значение переменной
$VerbosePreference для текущей команды. Поскольку по умолчанию для
переменной $VerbosePreference установлено значение SilentlyContinue,
подробные сообщения по умолчанию не отображаются.
Допустимые значения:
Значение $true (-Verbose:$true) равносильно использованию
параметра -Verbose без значения.
Значение $false (-Verbose:$false) подавляет отображение
подробных сообщений. Используйте этот параметр, если значение
переменной $VerbosePreference отличается от SilentlyContinue
(установлено по умолчанию).
-Debug[:{$true | $false}]
Отображает информацию о действиях, выполняемых командой,
которая может потребоваться программисту. Этот параметр будет
работать только с теми командами, которые генерируют
сообщения отладки. Например, этот параметр работает с командой,
содержащей командлет Write-Debug.
Параметр Debug переопределяет значение переменной
$DebugPreference для текущей команды. Поскольку по умолчанию для
переменной $DebugPreference установлено значение SilentlyContinue,
сообщения отладки по умолчанию не отображаются.
Допустимые значения:
$true (-Debug:$true). Равносильно использованию параметра
-Debug.
$false (-Debug:$false). Подавляет отображение сообщений
отладки, если для переменной $DebugPreference установлено
значение, отличное от SilentlyContinue (по умолчанию).
-WarningAction[:{SilentlyContinue | Continue | Inquire | Stop}]
Определяет реакцию командлета на возникновение предупреждения при
выполнении команды.
По умолчанию используется значение "Continue". Этот параметр будет
работать только с теми командами, которые генерируют предупреждения.
Например, этот параметр работает с командой, содержащей командлет
Write-Warning.
Параметр WarningAction переопределяет значение переменной
$WarningPreference для текущей команды. Поскольку по умолчанию для
переменной $WarningPreference установлено значение "Continue", если в
команде не используется параметр WarningAction, предупреждения
отображаются, а выполнение команды продолжается.
Допустимые значения:
SilentlyContinue. Подавление предупреждений и продолжение
выполнения команды.
Continue. Отображение предупреждения и продолжение выполнения
команды. По умолчанию используется значение "Continue".
Inquire. Отображение предупреждения, запрос на продолжение
выполнения. Это значение используется редко.
Stop. Отображение предупреждения, прекращение выполнения
команды.
-WarningVariable [+]<имя_переменной>
Сохраняет предупреждения о выполнении команды в указанной
переменной.
Для добавления предупреждений к значениям переменной вместо замены
предупреждений, которые могли быть сохранены в переменной раньше,
введите знак "плюс" (+) перед именем переменной.
Например, следующая команда создает переменную $a и сохраняет
в ней все предупреждения.
get-process -id 6 -WarningVariable a
Следующая команда добавляет все предупреждения в переменную $a.
get-process -id 2 -WarningVariable +a
Следующая команда отображает содержимое переменной $a.
$a
Этот параметр можно использовать для создания переменной, в
которой будут содержаться предупреждения о выполнении только
определенных команд. Для доступа к определенным предупреждениям,
хранящимся в переменной, можно использовать синтаксис работы
с массивами, например $a[0] или $warning[1,2].
-ErrorAction[:{SilentlyContinue | Continue | Inquire | Stop)]
Определяет реакцию командлета на возникновение непрерывающей
ошибки при выполнении команды. Этот параметр будет работать
только с теми командами, которые генерируют сообщения
отладки. Например, этот параметр работает с командой, содержащей
командлет Write-Error.
Параметр ErrorAction переопределяет значение переменной
$ErrorActionPreference для текущей команды. Поскольку по умолчанию для
переменной $ErrorActionPreference установлено значение "Continue", если
в команде не используется параметр ErrorAction, сообщения об ошибках
отображаются, а выполнение команды продолжается.
Параметр ErrorAction не влияет на обработку прерывающих
ошибок (включая отсутствие данных, неверные параметры или
недостаточные полномочия), препятствующих успешному завершению
выполнения команды.
Допустимые значения:
SilentlyContinue. Подавление сообщений об ошибках и
продолжение выполнения команды.
Continue. Отображение сообщений об ошибках, продолжение
выполнения команды. По умолчанию используется значение
"Continue".
Inquire. Отображение сообщения об ошибке, запрос на
продолжение выполнения. Это значение используется редко.
Stop. Отображение сообщения об ошибке и прекращение выполнения
команды.
-ErrorVariable [+]<имя_переменной>
Сохраняет сообщения об ошибках при выполнении команды в указанной
переменной и в автоматической переменной $Error. Чтобы получить
дополнительные сведения, введите следующую команду:
get-help about_automatic_variables
По умолчанию новые сообщения об ошибках перезапишут старые
сообщения об ошибках, уже хранящиеся в переменной. Для добавления
сообщения об ошибке к содержимому переменой введите знак "плюс" (+)
перед именем переменной.
Например, следующая команда создает переменную $a и сохраняет
в ней все сообщения об ошибках.
get-process -id 6 -ErrorVariable a
Следующая команда добавляет все сообщения об ошибках в
переменную a$.
get-process -id 2 -ErrorVariable +a
Следующая команда отображает содержимое переменной $a.
$a
Этот параметр можно использовать для создания переменной, в
которой будут содержаться сообщения об ошибках при выполнении
только определенных команд. В автоматической переменной $Error
сохраняются сообщения об ошибках при выполнении всех команд в рамках
сеанса. Для доступа к определенным сообщениям об ошибках, хранящимся в
переменной, можно использовать синтаксис работы с массивами, например
$a[0] или $error[1,2].
-OutVariable [+]<имя_переменной>
Сохраняет объекты выходных данных команды в указанной переменной и
отображает их в командной строке.
Для добавления выходных данных к значениям переменной вместо
замены выходных данных, которые могли быть сохранены в переменной
раньше, введите знак "плюс" (+) перед именем переменной.
Например, следующая команда создает переменную $out и
сохраняет в ней объект процесса.
get-process powershell -OutVariable out
Следующая команда добавляет в переменную $out объект процесса.
get-process iexplore -OutVariable +out
Следующая команда отображает содержимое переменной $out.
$out
-OutBuffer <Int32>
Определяет количество объектов, которое надо накопить в
буфере перед передачей объектов по конвейеру. Если этот
параметр не указан, объекты отправляются по мере создания.
Этот параметр управления ресурсами предназначен для опытных
пользователей.
При использовании этого параметра оболочка Windows PowerShell не
вызывает следующий командлет в конвейере до тех пор, пока количество
созданных объектов не станет равно OutBuffer + 1. После этого
оболочка посылает все объекты по мере создания.
Описания параметров управления рисками
-WhatIf[:{$true | $false}]
Отображает сообщение, в котором описан результат выполнения
команды, без фактического ее выполнения.
Параметр WhatIf переопределяет значение переменной
$WhatIfPreference для текущей команды. Поскольку по умолчанию для
переменной $WhatIfPreference установлено значение 0 (отключено),
функция WhatIf не используется, если в команде не указан параметр
WhatIf. Чтобы получить дополнительные сведения, введите следующую
команду:
get-help about_preference_variables
Допустимые значения:
$true (-WhatIf:$true). Равносильно использованию параметра -
WhatIf.
$false (-WhatIf:$false). Подавляет автоматическое
поведение WhatIf, которое наблюдается, если для переменной
$WhatIfPreference установлено значение 1.
Например, в следующей команде параметр WhatIf используется в
команде Remove-Item.
PS> remove-item date.csv -whatif
Вместо удаления элемента оболочка Windows PowerShell перечисляет
действия, которые могли бы быть предприняты, и затронутые элементы.
Эта команда выводит следующий текст:
What if: Выполнение операции "Удаление файла" над целевым
объектом "C:\ps-test\date.csv".
-Confirm[:{$true | $false}]
Запрашивает подтверждение перед выполнением команды.
Параметр Confirm переопределяет значение переменной
$ConfirmPreference для текущей команды. По умолчанию используется
значение High. Чтобы получить дополнительные сведения, введите
следующую команду:
get-help about_preference_variables
Допустимые значения:
$true (-WhatIf:$true). Равносильно использованию параметра -
Confirm.
$false(-Confirm:$false). Подавляет автоматическое
подтверждение, которое происходит, если значение переменной
$ConfirmPreference меньше или равно оценке риска выполнения
командлета.
Например, в следующей команде параметр Confirm используется в
в команде Remove-Item. Перед удалением элемента оболочка
Windows PowerShell перечисляет действия, которые могли бы быть
предприняты, и затронутые элементы, а также запрашивает
подтверждение выполняемой операции.
PS C:\ps-test> remove-item tmp*.txt -confirm
Эта команда выводит следующий текст:
Подтвердить
Выполнить это действие?
Выполнение операции "Удаление файла" над целевым объектом
" C:\ps-test\tmp1.txt [Y] Да [A] Да для всех [N] Нет [L]
Нет для всех [S] Приостановить [?] Справка (по умолчанию
"Y"):
СМ. ТАКЖЕ
about_Preference_Variables
Write-Debug
Write-Warning
Write-Error
Write-Verbose