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

Сведения о CommonParameters

  • Статья

КРАТКОЕ ОПИСАНИЕ

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

ПОДРОБНОЕ ОПИСАНИЕ

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

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

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

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

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

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

  • Debug (db)
  • ErrorAction (ea)
  • ErrorVariable (ev)
  • InformationAction (infa)
  • InformationVariable (iv)
  • OutVariable (ov)
  • OutBuffer (ob)
  • PipelineVariable (pv)
  • Подробный ( vb)
  • WarningAction (wa)
  • WarningVariable (wv)

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

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

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

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

Отладка

Псевдоним отладки — db.

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

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

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

ErrorAction

Псевдоним для ErrorAction — ea.

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

Параметр 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 Core, так как он доступен только для рабочих процессов.

Примечание

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

ErrorVariable

Псевдоним для ErrorVariable — ev.

ErrorVariable сохраняет сообщения об ошибках о команде в указанной переменной и в автоматической переменной $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] , чтобы ссылаться на определенные ошибки, хранящиеся в переменных.

InformationAction

Псевдоним для InformationAction — ia.

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

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

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

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

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

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

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

Примечание

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

InformationVariable

Псевдоним для InformationVariable — iv.

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

OutBuffer

Псевдоним для OutBuffer — ob и принимает значение System.Int32 .

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

Этот параметр управления ресурсами предназначен для опытных пользователей. При использовании этого параметра 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

Псевдоним outVariable — ov.

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

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

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

Get-Process PowerShell -OutVariable out

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

Get-Process iexplore -OutVariable +out

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

$out

Примечание

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

PipelineVariable

Псевдоним pipelineVariable — 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 , должны быть умножены, и указывает, что результаты должны отображаться как "Левый член диапазона * Правый член диапазона = продукт".

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 — vb.

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

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

-Verbose:$true имеет тот же эффект, что и -Verbose

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

WarningAction

Псевдоним warningAction — wa.

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

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

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

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

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

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

Примечание

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

WarningVariable

Псевдоним WarningVariable — wv.

Сохраняет предупреждения о команде в указанной переменной.

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

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

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

Get-Process -Id 6 -WarningVariable a

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

Get-Process -Id 2 -WarningVariable +a

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

$a

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

Примечание

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

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

WhatIf

Псевдоним для WhatIf — wi.

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

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

Get-Help 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 — cf.

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

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

Get-Help 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