Поделиться через

about_CommonParameters

  • Статья

Краткое описание

Описывает параметры, которые можно использовать с любым командлетом.

Подробное описание

Общие параметры — это набор параметров командлета, которые можно использовать с любым командлетом. Они реализованы PowerShell, а не разработчиком командлетов, и они автоматически доступны любому командлету.

Общие параметры можно использовать с любым командлетом, но они могут не влиять на все командлеты. Например, если командлет не создает подробные выходные данные, использование Verbose общего параметра не влияет.

Общие параметры также доступны в расширенных функциях, использующих CmdletBinding атрибут или Parameter атрибут. При использовании этих атрибутов PowerShell автоматически добавляет общие параметры. Невозможно создать какие-либо параметры, использующие те же имена, что и общие параметры.

Несколько распространенных параметров переопределяют системные значения по умолчанию или предпочтения, заданные с помощью переменных предпочтений PowerShell. В отличие от переменных предпочтения, общие параметры влияют только на команды, в которых они используются.

Дополнительные сведения см. в about_Preference_Variables.

В следующем списке отображаются общие параметры. Их псевдонимы перечислены в скобках.

  • Debug (db)
  • ErrorAction (ea)
  • ErrorVariable (ev)
  • InformationAction (infa)
  • InformationVariable (iv)
  • OutVariable (ov)
  • OutBuffer (ob)
  • PipelineVariable (pv)
  • ProgressAction (proga)
  • Verbose (vb)
  • WarningAction (wa)
  • WarningVariable (wv)

Параметры Действия — это значения типов ActionPreference . ActionPreference — это перечисление со следующими значениями:

Имя. Значение
Suspend 5
Ignore 4
Inquire 3
Continue 2
Stop 1
SilentlyContinue 0

Имя или значение можно использовать с параметром.

Помимо общих параметров, многие командлеты предлагают параметры устранения рисков. Командлеты, которые связаны с риском для системы или пользовательских данных, обычно предлагают эти параметры.

Параметры устранения рисков:

  • WhatIf (wi)
  • Confirm (cf)

Общие описания параметров

-Debug

Отображает сведения об операции, выполняемой командой на уровне программиста. Этот параметр работает только в том случае, если команда создает сообщение отладки. Например, этот параметр работает, если команда содержит Write-Debug командлет.

Type: SwitchParameter
Aliases: db
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

По умолчанию сообщения отладки не отображаются, так как значение переменной $DebugPreference имеет значение SilentlyContinue.

В интерактивном режиме Debug параметр переопределяет значение переменной $DebugPreference для текущей команды, задав значение $DebugPreference Inquire.

В неинтерактивном режиме Debug параметр переопределяет значение переменной $DebugPreference для текущей команды, задав значение $DebugPreference "Продолжить".

-Debug:$true имеет тот же эффект, что -Debugи . Используется -Debug:$false для подавления отображения сообщений отладки, если $DebugPreference это не SilentlyContinue, что является значением по умолчанию.

-ErrorAction

Определяет, как командлет реагирует на неисключаемую ошибку из команды. Этот параметр работает только в том случае, если команда создает неисключаемую ошибку, например из командлета Write-Error .

Type: ActionPreference
Aliases: ea
Accepted values: Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue

Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

Параметр ErrorAction переопределяет значение переменной $ErrorActionPreference для текущей команды. Так как значение переменной по умолчанию равно "Продолжить", сообщения об ошибках $ErrorActionPreference отображаются и выполняются, если не используется параметр ErrorAction.

Параметр ErrorAction не влияет на завершение ошибок (например, отсутствующих данных, параметров, не допустимых или недостаточных разрешений), которые препятствуют успешному выполнению команды.

  • -ErrorAction:Break Вводит отладчик при возникновении ошибки или возникновении исключения.
  • -ErrorAction:Continue отображает сообщение об ошибке и продолжает выполнять команду. Значение по умолчанию — Continue.
  • -ErrorAction:Ignore подавляет сообщение об ошибке и продолжает выполнять команду. В отличие от SilentlyContinue, ignore не добавляет сообщение об ошибке в автоматическую $Error переменную. Значение "Игнорировать" представлено в PowerShell 3.0.
  • -ErrorAction:Inquire отображает сообщение об ошибке и запрашивает подтверждение перед продолжением выполнения. Это значение редко используется.
  • -ErrorAction:SilentlyContinue подавляет сообщение об ошибке и продолжает выполнять команду.
  • -ErrorAction:Stop отображает сообщение об ошибке и останавливает выполнение команды.
  • -ErrorAction:Suspend доступен только для рабочих процессов, которые не поддерживаются в PowerShell 6 и более последующих версиях.

Примечание.

Параметр ErrorAction переопределяет, но не заменяет значение переменной $ErrorActionPreference при использовании параметра в команде для запуска скрипта или функции.

-ErrorVariable

Записи об ошибках автоматически хранятся в автоматической переменной $Error . Дополнительные сведения см. в статье about_Automatic_Variables.

При использовании параметра ErrorVariable в команде PowerShell также сохраняет записи об ошибках, создаваемые командой в переменной, указанной параметром.

Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

По умолчанию новые сообщения об ошибках перезаписывают сообщения об ошибках, которые уже хранятся в переменной. Чтобы добавить сообщение об ошибке в содержимое переменной, добавьте знак плюса (+) перед именем переменной.

Например, следующая команда создает переменную, а затем сохраняет в ней $a все ошибки:

Get-Process -Id 6 -ErrorVariable a

Следующая команда добавляет сообщения об ошибках в $a переменную:

Get-Process -Id 2 -ErrorVariable +a

Следующая команда отображает содержимое $a:

$a

Этот параметр можно использовать для создания переменной, которая содержит только сообщения об ошибках из определенных команд и не влияет на поведение автоматической переменной $Error . Автоматическая $Error переменная содержит сообщения об ошибках из всех команд в сеансе. Вы можете использовать нотацию массива, например $a[0] или $error[1,2] ссылаться на определенные ошибки, хранящиеся в переменных.

Примечание.

Пользовательская переменная ошибки содержит все ошибки, созданные командой, включая ошибки из вызовов вложенных функций или скриптов.

-InformationAction

Представлено в PowerShell 5.0. В команде или скрипте, в котором он используется, общий параметр InformationAction переопределяет значение переменной $InformationPreference предпочтения, которая по умолчанию имеет значение SilentlyContinue. При использовании Write-Information в скрипте с InformationAction значения отображаются в зависимости от значения параметра InformationActionWrite-Information. Дополнительные сведения см. в $InformationPreferenceabout_Preference_Variables.

Type: ActionPreference
Aliases: infa
Accepted values: Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue

Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
  • -InformationAction:Break Введите отладчик при вхождании Write-Information команды.
  • -InformationAction:Stop останавливает команду или скрипт при вхождании Write-Information команды.
  • -InformationAction:Ignore подавляет информационное сообщение и продолжает выполнять команду. В отличие от SilentlyContinue, игнорировать полностью забывает информационное сообщение; он не добавляет информационное сообщение в поток информации.
  • -InformationAction:Inquire отображает информационное сообщение, указанное в команде Write-Information , а затем задает вопрос о том, следует ли продолжить.
  • -InformationAction:Continue отображает информационное сообщение и продолжает работать.
  • -InformationAction:Suspend Не поддерживается в PowerShell 6 и более поздних версиях, так как он доступен только для рабочих процессов.
  • -InformationAction:SilentlyContinue не действует, так как информационное сообщение не отображается (по умолчанию), и сценарий продолжается без прерывания.

Примечание.

Параметр InformationAction переопределяет, но не заменяет значение переменной $InformationAction предпочтения при использовании параметра в команде для запуска скрипта или функции.

-InformationVariable

Представлено в PowerShell 5.0. При использовании общего параметра InformationVariable записи сведений хранятся в переменной, указанной параметром. Командлет PowerShell может записывать записи информации в поток сведений. Можно также использовать Write-Information командлет для записи записей информации.

Записи сведений отображаются в виде сообщений в консоли по умолчанию. Вы можете управлять отображением записей информации с помощью общего параметра InformationAction . Вы также можете изменить поведение с помощью переменной $InformationPreference предпочтения. Дополнительные сведения см. в $InformationPreferenceabout_Preference_Variables.

Примечание.

Переменная сведений содержит все информационные сообщения, созданные командой, включая информационные сообщения из вызовов вложенных функций или скриптов.

Type: String
Aliases: iv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

По умолчанию новые значения записей сведений перезаписываются, которые уже хранятся в переменной. Чтобы добавить сообщение об ошибке в содержимое переменной, добавьте знак плюса (+) перед именем переменной.

-OutBuffer

Определяет количество объектов, накапливаемых в буфере, прежде чем все объекты отправляются через конвейер. Если этот параметр не указан, объекты отправляются по мере их создания.

Type: Int32
Aliases: ob
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Этот параметр управления ресурсами предназначен для расширенных пользователей. При использовании этого параметра PowerShell отправляет данные в следующий командлет в пакетах OutBuffer + 1.

В следующем примере отображаются варианты между ForEach-Object блоками обработки, которые используют Write-Host командлет. Отображение альтернативных вариантов в пакетах из 2 или OutBuffer + 1.

1..4 | ForEach-Object {
        Write-Host "$($_): First"; $_
      } -OutBuffer 1 | ForEach-Object {
                        Write-Host "$($_): Second" }

1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second

-OutVariable

Сохраняет выходные объекты из команды в указанной переменной в дополнение к отправке выходных данных по конвейеру.

Type: String
Aliases: ov
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Чтобы добавить выходные данные в переменную, вместо замены любых выходных данных, которые уже могут храниться там, введите знак плюса (+) перед именем переменной.

Например, следующая команда создает $out переменную и сохраняет объект процесса в нем:

Get-Process PowerShell -OutVariable out

Следующая команда добавляет объект процесса в $out переменную:

Get-Process iexplore -OutVariable +out

Следующая команда отображает содержимое переменной $out :

$out

Примечание.

Переменная, созданная параметром OutVariable, является .[System.Collections.ArrayList]

-PipelineVariable

PipelineVariable позволяет получить доступ к последнему значению, передаваемому в следующий сегмент конвейера командой, которая использует этот параметр. Любая команда в конвейере может получить доступ к значению с помощью именованного PipelineVariable. Значение присваивается переменной при передаче в следующий сегмент конвейера. Это упрощает использование PipelineVariable , чем определенную временную переменную, которую может потребоваться назначить в нескольких расположениях.

В отличие $_ от того, $PSItemчто использование PipelineVariable позволяет любой команде конвейера получать доступ к значениям конвейера, переданным (и сохраненным) командами, отличными от непосредственно предыдущей команды. Команды конвейера могут получить доступ к последнему каналу значений при обработке следующего элемента, передаваемого через конвейер. Это позволяет команде передавать выходные данные в предыдущую команду (или сама по себе).

Примечание.

Расширенные функции могут содержать до трех блоков скриптов: begin, processи end. При использовании параметра PipelineVariable с расширенными функциями только значения из первого определенного блока скрипта назначаются переменной в качестве запуска функции. Дополнительные сведения см. в разделе "Дополнительные функции". PowerShell 7.2 исправляет это поведение.

Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Допустимые значения — это строки, аналогичные любым именам переменных.

Внимание

PipelineVariable ограничен конвейером, в котором он вызывается. Переменные за пределами конвейера, которые используют то же имя, очищаются перед выполнением конвейера. КонвейерVariable выходит из области при завершении конвейера. Если несколько команд в конвейере указывают один и тот же PipelineVariable , то существует только одна общая переменная. Эта переменная обновляется с последними выходными данными из команды, указывающей переменную.

Некоторые команды блокировки собирают все элементы конвейера перед созданием выходных данных, например Sort-Object или Select-Object -Last. Любой конвейерVariable , назначенный в команде перед такой командой блокировки, всегда содержит конечный элемент из предыдущей команды при использовании в команде после команды блокировки.

Ниже приведен пример работы PipelineVariable . В этом примере параметр PipelineVariable добавляется в Foreach-Object команду для хранения результатов команды в переменных. Диапазон чисел, от 1 до 5, передаются в первую Foreach-Object команду, результаты которых хранятся в переменной с именем $temp.

Результаты первой Foreach-Object команды передаются во вторую Foreach-Object команду, которая отображает текущие значения $temp и $_.

# Create a variable named $temp
$temp=8
Get-Variable temp
# Note that the variable just created isn't available on the
# pipeline when -PipelineVariable creates the same variable name
1..5 | ForEach-Object -PipelineVariable temp -Begin {
    Write-Host "Step1[BEGIN]:`$temp=$temp"
} -Process {
  Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
  Write-Output $_
} | ForEach-Object {
  Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
}
# The $temp variable is deleted when the pipeline finishes
Get-Variable temp

Name                           Value
----                           -----
temp                           8

Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
        Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
        Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
        Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
        Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
        Step2[PROCESS]:$temp=5 - $_=5

Get-Variable : Cannot find a variable with the name 'temp'.
At line:1 char:1
+ Get-Variable temp
+ ~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (temp:String) [Get-Variable], ItemNotFoundException
    + FullyQualifiedErrorId : VariableNotFound,Microsoft.PowerShell.Commands.GetVariableCommand

-ProgressAction

Определяет, как PowerShell реагирует на обновления хода выполнения, созданные скриптом, командлетом или поставщиком, например индикаторами хода выполнения, созданными командлетом Write-Progress . Командлет Write-Progress создает индикаторы хода выполнения, показывающие состояние команды. Параметр ProgressAction добавлен в PowerShell 7.4.

Параметр ProgressAction принимает одно из ActionPreference значений перечисления: SilentlyContinue, Stop, Continue, , Inquire, SuspendIgnoreили Break.

Допустимы следующие значения.

  • Break Введите отладчик при вхождании Write-Progress команды.
  • Stop: не отображает индикатор хода выполнения. Вместо этого отображается сообщение об ошибке и останавливается выполнение.
  • Inquire: не отображает индикатор хода выполнения. Запрашивает разрешение на продолжение. При ответе на Y запрос или Aотображается индикатор хода выполнения.
  • Continue: (по умолчанию) Отображает индикатор хода выполнения и продолжает выполнение.
  • SilentlyContinue: выполняет команду, но не отображает индикатор выполнения.
Type: ActionPreference
Aliases: proga
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

-Verbose

Отображает подробные сведения об операции, выполняемой командой. Эта информация напоминает сведения в трассировке или в журнале транзакций. Этот параметр работает только в том случае, если команда создает подробное сообщение. Например, этот параметр работает, если команда содержит Write-Verbose командлет.

Type: SwitchParameter
Aliases: vb
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

Параметр Verbose переопределяет значение переменной $VerbosePreference для текущей команды. Так как значение переменной $VerbosePreference по умолчанию — SilentlyContinue, подробные сообщения не отображаются по умолчанию.

  • -Verbose:$true имеет тот же эффект, что и -Verbose
  • -Verbose:$false подавляет отображение подробных сообщений. Используйте этот параметр, если значение $VerbosePreference не является SilentlyContinue (по умолчанию).

-WarningAction

Определяет, как командлет реагирует на предупреждение из команды. Продолжить — это значение по умолчанию. Этот параметр работает только в том случае, если команда создает предупреждение. Например, этот параметр работает, если команда содержит Write-Warning командлет.

Type: ActionPreference
Aliases: wa
Accepted values: Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue

Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

Параметр WarningAction переопределяет значение переменной $WarningPreference для текущей команды. Так как значение переменной $WarningPreference по умолчанию равно "Продолжить", предупреждения отображаются и выполняются, если вы не используете параметр WarningAction .

  • -WarningAction:Break вводит отладчик при возникновении предупреждения.
  • -WarningAction:Continue отображает предупреждения и продолжает выполнять команду. Значение по умолчанию — Continue.
  • -WarningAction:Inquire отображает предупреждение и запрашивает подтверждение перед продолжением выполнения. Это значение редко используется.
  • -WarningAction:SilentlyContinue подавляет предупреждение и продолжает выполнять команду.
  • -WarningAction:Stop отображает предупреждение и останавливает выполнение команды.

Примечание.

Параметр WarningAction переопределяет, но не заменяет значение переменной $WarningAction предпочтения при использовании параметра в команде для запуска скрипта или функции.

-WarningVariable

Хранит записи предупреждений о команде в указанной переменной.

Type: String
Aliases: wv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Все созданные предупреждения сохраняются в переменной, даже если предупреждения не отображаются пользователю.

Чтобы добавить предупреждения к содержимому переменной, вместо замены любых предупреждений, которые уже могут храниться там, введите знак плюса (+) перед именем переменной.

Например, следующая команда создает переменную, а затем сохраняет в ней $a все предупреждения:

Get-Process -Id 6 -WarningVariable a

Следующая команда добавляет все предупреждения в $a переменную:

Get-Process -Id 2 -WarningVariable +a

Следующая команда отображает содержимое $a:

$a

Этот параметр можно использовать для создания переменной, содержащей только предупреждения из определенных команд. Вы можете использовать нотацию массива, например $a[0] или $warning[1,2] ссылаться на определенные предупреждения, хранящиеся в переменной.

Примечание.

Переменная предупреждения содержит все предупреждения, созданные командой, включая предупреждения от вызовов вложенных функций или скриптов.

Описания параметров управления рисками

-WhatIf

Отображает сообщение, описывающее эффект команды, а не выполнение команды.

Type: SwitchParameter
Aliases: wi
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

Параметр WhatIf переопределяет значение переменной $WhatIfPreference для текущей команды. Так как значение переменной $WhatIfPreference по умолчанию равно 0 (отключено), поведение WhatIf не выполняется без параметра WhatIf . Дополнительные сведения см. в about_Preference_Variables.

  • -WhatIf:$true имеет тот же эффект, что -WhatIfи .
  • -WhatIf:$false подавляет автоматическое поведение WhatIf, которое приводит к значению переменной $WhatIfPreference 1.

Например, следующая команда использует -WhatIf параметр в команде Remove-Item :

Remove-Item Date.csv -WhatIf

Вместо удаления элемента PowerShell выводит список выполняемых операций и затронутых элементов. Эта команда выдает следующий результат:

What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".

-Confirm

Выводит приглашение для подтверждения перед выполнением команды.

Type: SwitchParameter
Aliases: cf
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

Параметр Confirm переопределяет значение переменной $ConfirmPreference для текущей команды. Значение по умолчанию — true. Дополнительные сведения см. в about_Preference_Variables.

  • -Confirm:$true имеет тот же эффект, что -Confirmи .
  • -Confirm:$false подавляет автоматическое подтверждение, которое возникает, когда значение $ConfirmPreference меньше или равно предполагаемому риску командлета.

Например, следующая команда использует Confirm параметр с командой Remove-Item . Перед удалением элемента 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 ответа приведены следующим образом:

Response Результат
Yes (Y) Выполните действие.
Yes to All (A) Выполнение всех действий и отключение последующих действий Confirm
запросы для этой команды.
No (N): Не выполняйте действие.
No to All (L): Не выполняйте никаких действий и не подавляйте последующие действия
Confirm запросы для этой команды.
Suspend (S): Приостанавливайте команду и создайте временный сеанс.
Help (?) Отображение справки по этим параметрам.

Параметр "Приостановка " помещает команду на удержание и создает временный вложенный сеанс, в котором можно работать до тех пор, пока не будете готовы выбрать Confirm вариант. В командной строке вложенного сеанса есть два дополнительных курсора (>>), чтобы указать, что это дочерняя операция исходной родительской команды. Команды и скрипты можно выполнять в вложенном сеансе. Чтобы завершить вложенный сеанс и вернуться к Confirm параметрам исходной команды, введите "exit".

В следующем примере параметр приостановки (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 (defau
lt is "Y"): y

Directory: C:\ps-test

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         8/27/2010   2:41 PM          0 test.txt

См. также