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

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)

Параметры Action — это значения типа 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 значение 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 не влияет на устранимые ошибки (например, отсутствующие данные, недопустимые параметры или недостаточные разрешения), которые препятствуют успешному выполнению команды.

  • Break Вводит отладчик при возникновении ошибки или возникновении исключения.
  • Continue отображает сообщение об ошибке и продолжает выполнение команды. Значение по умолчанию — Continue.
  • Ignore подавляет сообщение об ошибке и продолжает выполнение команды. В отличие от SilentlyContinue, Ignore не добавляет сообщение об ошибке в автоматическую $Error переменную. Значение Ignore появилось в PowerShell 3.0.
  • Inquire отображает сообщение об ошибке и запрашивает подтверждение перед продолжением выполнения. Это значение используется редко.
  • SilentlyContinue подавляет сообщение об ошибке и продолжает выполнение команды.
  • Stop отображает сообщение об ошибке и прекращает выполнение команды.
  • 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 в скрипте с InformationActionWrite-Information значения отображаются в зависимости от значения параметра InformationAction. Дополнительные сведения о $InformationPreferenceсм. в разделе about_Preference_Variables.

Type: ActionPreference
Aliases: infa
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
  • Break Вводит отладчик при вхождлении Write-Information команды .
  • Stop останавливает команду или скрипт при вхождлении Write-Information команды.
  • Ignore подавляет информационное сообщение и продолжает выполнение команды. В отличие от SilentlyContinue, Ignore полностью забывает информационное сообщение; оно не добавляет информационное сообщение в информационный поток.
  • Inquire отображает информационное сообщение, указанное в команде Write-Information , а затем запрашивает, хотите ли вы продолжить.
  • Continue отображает информационное сообщение и продолжает выполняться.
  • Suspend не поддерживается в PowerShell 6 и более поздних версиях, так как доступен только для рабочих процессов.
  • SilentlyContinue нет эффекта, так как информационное сообщение не отображается (по умолчанию), и скрипт продолжает работу без прерывания.

Примечание

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

-InformationVariable

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

Информационные записи по умолчанию отображаются в консоли в виде сообщений. Отображением информационной записи можно управлять с помощью общего параметра InformationAction . Вы также можете изменить поведение с помощью переменной $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 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

Name                           Value
----                           -----
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 .

  • Break входит в отладчик при появлении предупреждения.
  • Continue отображает предупреждающие сообщения и продолжает выполнение команды. Значение по умолчанию — Continue.
  • Inquire отображает предупреждение и запрашивает подтверждение перед продолжением выполнения. Это значение используется редко.
  • SilentlyContinue подавляет предупреждающее сообщение и продолжает выполнение команды.
  • 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.

  • $true имеет тот же эффект, что и -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.

  • $true имеет тот же эффект, что и -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

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