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

Сведения о 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)
  • Подробный ( vb)
  • WarningAction (wa)
  • WarningVariable (wv)

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

Имя Значение
Приостановить 5
Игнорировать 4
Inquire 3
Продолжить 2
Stop 1
SilentlyContinue 0

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

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

Ниже приведены параметры устранения рисков.

  • WhatIf (wi)
  • Подтверждение (cf)

ОБЩИЕ ОПИСАНИЯ ПАРАМЕТРОВ

Отладка

Отображает сведения на уровне программиста об операции, выполненной командой . Этот параметр работает только в том случае, если команда создает сообщение об отладке. Например, этот параметр работает, если команда содержит 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: 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: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: 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:Stop останавливает команду или скрипт при вхождлении Write-Information команды.

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

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

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

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

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

Type: String
Aliases: pv

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

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

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

Результаты первой Foreach-Object команды передаются во вторую Foreach-Object команду, которая фильтрует объекты, возвращаемые первой Foreach-Object командой. Результаты второй команды хранятся в переменной Right.

В третьей Foreach-Object команде результаты первых двух Foreach-Object команд, представленных переменными 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
...

Подробный

Отображает подробные сведения об операции, выполненной командой . Эти сведения похожи на сведения в трассировке или в журнале транзакций. Этот параметр работает, только если команда создает подробное сообщение. Например, этот параметр работает, если команда содержит 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 по умолчанию — Continue, отображаются предупреждения и выполнение продолжается, если не использовать параметр WarningAction .

-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".

Подтвердить

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

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

Ниже приведены параметры подтверждения ответа.

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

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

В следующем примере параметр Suspend (S) используется для временной остановки команды, пока пользователь проверяет справку на наличие параметра команды. Получив необходимые сведения, пользователь вводит "exit" для завершения вложенного запроса, а затем выбирает ответ Да (y) на запрос Подтверждения.

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

КЛЮЧЕВЫЕ СЛОВА

about_Common_Parameters

СМ. ТАКЖЕ

about_Preference_Variables

Write-Debug

Write-Warning

Write-Error

Write-Verbose