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

about_CommonParameters

  • Статья

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

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

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

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

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

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

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

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

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

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

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

Имя Значение
Break 6
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

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

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

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

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

-ErrorAction

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

Type: ActionPreference
Aliases: ea
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

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

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

-ErrorAction:Break Вводит отладчик при возникновении ошибки или возникновении исключения.

-ErrorAction:Continue отображает сообщение об ошибке и продолжает выполнение команды. Значение по умолчанию — Continue.

-ErrorAction:Ignore подавляет сообщение об ошибке и продолжает выполнение команды. В отличие от SilentlyContinue, ignore не добавляет сообщение об ошибке в автоматическую $Error переменную. Значение Ignore появилось в PowerShell 3.0.

-ErrorAction:Inquire отображает сообщение об ошибке и запрашивает подтверждение перед продолжением выполнения. Это значение используется редко.

-ErrorAction:SilentlyContinue подавляет сообщение об ошибке и продолжает выполнение команды.

-ErrorAction:Stop отображает сообщение об ошибке и прекращает выполнение команды.

-ErrorAction:Suspend доступен только для рабочих процессов, которые не поддерживаются в PowerShell 6 и более подробных версиях.

Примечание

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

-ErrorVariable

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

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 в скрипте с InformationActionWrite-Information значения отображаются в зависимости от значения параметра InformationAction. Дополнительные сведения о $InformationPreferenceсм. в разделе about_Preference_Variables.

Type: ActionPreference
Aliases: ia
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

-InformationAction:Break Вводит отладчик при вхождлении Write-Information команды .

-InformationAction:Stop останавливает команду или скрипт при вхождлении Write-Information команды.

-InformationAction:Ignore подавляет информационное сообщение и продолжает выполнение команды. В отличие от SilentlyContinue, Ignore полностью забывает информационное сообщение; оно не добавляет информационное сообщение в поток информации.

-InformationAction:Inquire отображает информационное сообщение, указанное в команде Write-Information , а затем запрашивает, хотите ли вы продолжить.

-InformationAction:Continue отображает информационное сообщение и продолжает выполняться.

-InformationAction:Suspend не поддерживается в PowerShell 6 и более поздних версиях, так как доступен только для рабочих процессов.

-InformationAction:SilentlyContinue нет эффекта, так как информационное сообщение не отображается (по умолчанию), и сценарий продолжается без прерываний.

Примечание

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

-InformationVariable

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

Примечание

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

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 ограничен конвейером, в котором он вызывается. Переменные за пределами конвейера, использующие то же имя, удаляются перед выполнением конвейера. PipelineVariable выходит из область при завершении конвейера. Если несколько команд в конвейере указывают один и тот же PipelineVariable , то существует только одна общая переменная. Эта переменная обновляется самыми последними выходными данными, полученными от команды, указывающей переменную .

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

Ниже приведен пример работы 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 is not 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'.

-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: 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

Параметр WarningAction переопределяет значение переменной $WarningPreference для текущей команды. Так как значение переменной $WarningPreference по умолчанию — Continue, отображаются предупреждения и выполнение продолжается, если не использовать параметр 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] .

Примечание

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

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

-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 приведены варианты ответа.

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

Параметр Приостановить помещает команду на удержание и создает временный вложенный сеанс, в котором можно работать до тех пор, пока не будете готовы к выбору 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 (defau
lt is "Y"): y

Directory: C:\ps-test

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

Keywords

about_Common_Parameters

См. также раздел