about_CommonParameters
Назначение: Windows PowerShell 2.0, Windows PowerShell 3.0
Вставьте сюда введение.
РАЗДЕЛ
about_CommonParameters
КРАТКОЕ ОПИСАНИЕ
Описание параметров, которые могут использоваться с любым командлетом.
ПОДРОБНОЕ ОПИСАНИЕ
Общие параметры представляют собой набор параметров командлетов, который можно использовать с любым командлетом. Их реализует Windows PowerShell®, а не разработчик командлетов, и они автоматически становятся доступными для любого командлета.
Общие параметры можно использовать с любым командлетом, но они могут влиять лишь на некоторые командлеты. Например, если командлет не выводит подробные данные, использование общего параметра Verbose ни на что не влияет.
Общие параметры также доступны в дополнительных функциях, использующих атрибут CmdletBinding или атрибут Parameter, и во всех рабочих процессах.
Несколько общих параметров переопределяют системные параметры по умолчанию или настройки, выполняемые с помощью привилегированных переменных Windows PowerShell. В отличие от привилегированных переменных общие параметры влияют только на те команды, в которых они используются.
Помимо общих параметров многие командлеты предлагают параметры снижения рисков WhatIf и Confirm. Эти параметры обычно предоставляются командлетами, которые создают риск для системы или данных пользователей.
Ниже приведен список общих параметров. Их псевдонимы указаны в скобках.
-Debug (db)
-ErrorAction (ea)
-ErrorVariable (ev)
-OutVariable (ov)
-OutBuffer (ob)
-PipelineVariable (pv)
-Verbose (vb)
-WarningAction (wa)
-WarningVariable (wv
Существуют следующие параметры устранения рисков:
-WhatIf (wi)
-Confirm (cf)
Чтобы получить дополнительные сведения о привилегированных переменных, введите:
help about_Preference_Variables
ОПИСАНИЕ ОБЩИХ ПАРАМЕТРОВ
-DEBUG[:{$TRUE | $FALSE}]
Alias: db
Выводит подробные сведения об операции, выполняемой командой, на уровне программного кода. Этот параметр работает только в том случае, если команда создает сообщение отладки. Например, этот параметр работает, если команда содержит командлет Write-Debug.
Параметр Debug переопределяет значение переменной $DebugPreference для текущей команды, задавая Inquire в качестве значения переменной $DebugPreference. Поскольку переменная $DebugPreference имеет значение по умолчанию SilentlyContinue, сообщения об отладке не отображаются по умолчанию.
Допустимые значения:
$true (-Debug:$true). Has the same effect as -Debug.
$false (-Debug:$false). Suppresses the display of debugging
messages when the value of the $DebugPreference is not
SilentlyContinue (the default).
-ERRORACTION[:{CONTINUE | IGNORE | INQUIRE | SILENTLYCONTINUE | STOP |SUSPEND }]
Alias: ea
Определяет способ реагирования командлета на некритическую ошибку из команды. Этот параметр действует только в том случае, если команда создает устранимую ошибку, например от командлета Write-Error.
Параметр ErrorAction переопределяет значение переменной $ErrorActionPreference для текущей команды. Поскольку переменная $ErrorActionPreference имеет значение по умолчанию Continue, отображаются сообщения об ошибке, и выполнение продолжается до тех пор, пока не будет использоваться параметр ErrorAction.
Параметр ErrorAction не оказывает влияния на неустранимые ошибки (например, отсутствие данных, недопустимые параметры, недостаточные разрешения), которые препятствуют успешному завершению команды.
Допустимые значения:
Continue. Выводится сообщение об ошибке, и выполнение команды продолжается. Continue является значением по умолчанию.
Ignore. Сообщение об ошибке не выводится, и выполнение команды продолжается. В отличие от SilentlyContinue значение Ignore не добавляет сообщение об ошибке в автоматическую переменную $Error. Значение Ignore впервые представлено в Windows PowerShell 3.0.
Inquire. Отображает сообщение об ошибке и запрашивает подтверждение перед продолжением выполнения. Это значение используется редко.
SilentlyContinue. Сообщение об ошибке не выводится, и выполнение команды продолжается.
Stop. Отображает сообщение об ошибке и прекращает выполнение команды.
Suspend. Это значение доступно только в рабочих процессах Windows PowerShell. Когда в рабочем процессе возникает неустранимая ошибка, этот параметр действия автоматически приостанавливает выполнение задания, позволяя изучить ситуацию. После исследования рабочий процесс можно возобновить.
-ERRORVARIABLE [+]<VARIABLE-NAME>
Alias: ev
Хранит сообщения об ошибках в команде в указанной переменной и автоматической переменной $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].
-OUTBUFFER <INT32>
Alias: ob
Определяет количество объектов, накапливаемых в буфере перед отправкой объектов по конвейеру. Если этот параметр не указан, объекты будут отправляться по мере их создания.
Этот параметр управления ресурсами предназначен для опытных пользователей. При использовании этого параметра Windows PowerShell не вызывает следующий командлет в конвейере, пока число созданных объектов не будет равно OutBuffer + 1. После этого он отправит все созданные объекты.
-OUTVARIABLE [+]<VARIABLE-NAME>
Alias: ov
Хранит объекты выходных данных из команды в указанной переменной и отображает ее в командной строке.
Чтобы добавить выходные данные в переменную вместо замены выходных данных, которые уже могут там храниться, введите знак «плюс» (+) перед именем переменной.
Например, следующая команда создает переменную $out и сохраняет в ней объект процесса:
Get-Process PowerShell -OutVariable out
Следующая команда добавляет объект процесса в переменную $out:
Get-Process iexplore -OutVariable +out
Следующая команда отображает содержимое переменной $out:.
$out
-PIPELINEVARIABLE <STRING>
Alias: pv
PipelineVariable сохраняет значение текущего элемента конвейера в виде переменной для любой именованной команды, проходящей по конвейеру.
Допустимыми значениями являются строки, так же как для любых имен переменных.
Ниже приведен пример действия параметра PipelineVariable. В этом примере параметр PipelineVariable добавляется в команду Foreach-Object для сохранения результатов выполнения команды в переменных. Диапазон чисел от 1 до 10 передается по конвейеру в первую команду Foreach-Object, результаты которой сохраняются в переменной с именем Left.
Результаты выполнения первой команды Foreach-Object передаются по конвейеру во вторую команду Foreach-Object, которая фильтрует объекты, возвращаемые первой командой Foreach-Object. Результаты выполнения второй команды сохраняются в переменной с именем Right.
В третьей команде Foreach-Object результаты выполнения двух первых переданных по конвейеру команд Foreach-Object, представленные переменными Left и Right, обрабатываются с использованием оператора умножения. Команда указывает, что объекты, хранящиеся в переменных Left и Right, должны быть перемножены, а результаты должны отображаться в виде «Элемент диапазона Left * Элемент диапазона Right = продукт».
1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
>> Foreach-Object -PV Right -Process { 1..10 } |
>> Foreach-Object -Process { "$Left * $Right = " + ($Left * $Right) }
>>
1 * 1 = 1
1 * 2 = 2
1 * 3 = 3
1 * 4 = 4
1 * 5 = 5
-VERBOSE[:{$TRUE | $FALSE}]
Alias: vb
Отображает подробные сведения об операции, выполняемой командой. Эта информация похожа на сведения в журнале трассировки или транзакций. Этот параметр работает только в том случае, если команда создает подробное сообщение. Например, этот параметр работает, если команда содержит командлет Write-Verbose.
Параметр Verbose переопределяет значение переменной $VerbosePreference для текущей команды. Поскольку переменная $VerbosePreference имеет значение по умолчанию SilentlyContinue, подробные сообщения не отображаются по умолчанию.
Допустимые значения:
$true (-Verbose:$true) has the same effect as -Verbose.
$false (-Verbose:$false) suppresses the display of verbose
messages. Use this parameter when the value of $VerbosePreference
is not SilentlyContinue (the default).
-WARNINGACTION[:{CONTINUE | INQUIRE | SILENTLYCONTINUE | STOP}]
Alias: wa
Определяет способ реагирования командлета на предупреждение из команды. Continue является значением по умолчанию. Этот параметр работает только в том случае, если команда создает предупреждающее сообщение. Например, этот параметр работает, если команда содержит командлет Write-Warning.
Параметр WarningAction переопределяет значение переменной $WarningPreference для текущей команды. Поскольку переменная $WarningPreference имеет значение по умолчанию Continue, отображаются предупреждения, и выполнение продолжается до тех пор, пока не будет использоваться параметр WarningAction.
Допустимые значения:
Continue. Отображает предупреждающее сообщение и продолжает выполнение команды. Continue является значением по умолчанию.
Inquire. Отображает предупреждающее сообщение и запрашивает подтверждение перед продолжением выполнения. Это значение используется редко.
SilentlyContinue. Подавляет вывод предупреждающего сообщения и продолжает выполнение команды.
Stop. Отображает предупреждающее сообщение и прекращает выполнение команды.
ПРИМЕЧАНИЕ. Параметр WarningAction не переопределяет значение привилегированной переменной $WarningAction при использовании в команде для запуска сценария или функции.
-WARNINGVARIABLE [+]<VARIABLE-NAME>
Alias: wv
Хранит предупреждения о команде в указанной переменной.
Все созданные предупреждения сохраняются в переменной, даже если предупреждения не отображаются для пользователя.
Чтобы добавить предупреждения в содержимое переменной вместо их замены предупреждениями, которые уже могут там храниться, введите знак «плюс» (+) перед именем переменной.
Например, следующая команда создает переменную $a и сохраняет в ней все предупреждения:
Get-Process -Id 6 -WarningVariable a
Следующая команда добавляет все предупреждения в переменную $a:
Get-Process -Id 2 -WarningVariable +a
Следующая команда отображает содержимое переменной $a:
$a
Этот параметр можно использовать для создания переменной, содержащей предупреждения только из определенных команд. Для ссылки на конкретные предупреждения, хранящиеся в переменной, можно использовать нотацию массива, например $a[0] или $warning[1,2].
ПРИМЕЧАНИЕ. Параметр WarningVariable не собирает предупреждения из вложенных вызовов в функциях или сценариях.
ОПИСАНИЕ ПАРАМЕТРОВ УПРАВЛЕНИЯ РИСКАМИ
-WHATIF[:{$TRUE | $FALSE}]
Alias: wi
Отображает сообщение, в котором объясняется результат команды, но сама команда не выполняется.
Параметр WhatIf переопределяет значение переменной $WhatIfPreference для текущей команды. Поскольку переменная $WhatIfPreference имеет значение по умолчанию 0 (отключено), поведение WhatIf без параметра WhatIf не осуществляется. Для получения дополнительных сведений введите следующую команду:
Get-Help about_Preference_Variables
Допустимые значения:
$true (-WhatIf:$true). Has the same effect as -WhatIf.
$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
that results when the value of the $WhatIfPreference variable
is 1.
Например, следующая команда использует параметр WhatIf в команде Remove-Item:
PS> Remove-Item Date.csv -WhatIf
Вместо удаления элемента Windows PowerShell перечисляет операции, которые будут выполнены, и элементы, которые будут затронуты. Команда выводит следующий результат:
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
-CONFIRM[:{$TRUE | $FALSE}]
Alias: cf
Запрос подтверждения перед выполнением команды.
Параметр Confirm переопределяет значение переменной $ConfirmPreference для текущей команды. Значение по умолчанию — High. Для получения дополнительных сведений введите следующую команду:
Get-Help about_Preference_Variables
Допустимые значения:
$true (-Confirm:$true). Has the same effect as -Confirm.
$false(-Confirm:$false). Suppresses automatic confirmation,
which occurs when the value of $ConfirmPreference is less than
or equal to the estimated risk of the cmdlet.
Например, следующая команда использует параметр Confirm в команде Remove-Item. Перед удалением элемента Windows PowerShell перечисляет операции, которые будут выполнены, элементы, которые будут затронуты, и запрашивает утверждение.
PS C:\ps-test> Remove-Item tmp*.txt -Confirm
Команда выводит следующий результат:
Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend
[?] Help (default is "Y"):
Далее приведены параметры ответа Confirm:
Yes (Y) Perform the action.
Yes to All (A) Perform all actions and suppress subsequent
Confirm queries for this command.
No (N): Do not perform the action.
No to All (L): Do not perform any actions and suppress subsequent
Confirm queries for this command.
Suspend (S): Pause the command and create a temporary session.
Help (?) Display help for these options.
Параметр Suspend переводит команду в режим удержания и создает временный вложенный сеанс, в котором можно работать до выбора параметра Confirm. В командной строке для вложенного сеанса существуют две дополнительные «крышки» (>>) для указания дочерней операции исходной родительской команды. Во вложенных сеансах можно выполнять команды и сценарии. Чтобы завершить вложенный сеанс и вернуться к параметрам Confirm для исходной команды, введите «exit».
В следующем примере параметр Suspend (S) используется для временной остановки команды, пока пользователь просматривает справку по параметру команды. После получения необходимой информации пользователь вводит «exit», чтобы завершить вложенный запрос, и затем выбирает ответ «Да» (y) на запрос Confirm.
PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm
Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): s
PS C:\ps-test>>> Get-Help New-Item -Parameter ItemType
-ItemType <string>
Specifies the provider-specified type of the new item.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
PS C:\ps-test>>> exit
Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y
Directory: C:\ps-test
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 8/27/2010 2:41 PM 0 test.txt
КЛЮЧЕВЫЕ СЛОВА
about_Common_Parameters
СМ. ТАКЖЕ
about_Preference_Variables
Write-Debug
Write-Warning
Write-Error
Write-Verbose