about_CommonParameters

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

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

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

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

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

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

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

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

• 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 "Продолжить".

-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 отображаются и выполняются, если не используется параметр ErrorAction.

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

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

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

-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

-PipelineVariable

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

В отличие $_ от того, $PSItemчто использование 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 до 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

-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

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

• -Verbose:$true имеет тот же эффект, что и -Verbose
• -Verbose:$false подавляет отображение verbose сообщений. Используйте этот параметр, если значение $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 по умолчанию равно "Продолжить", предупреждения отображаются и выполняются, если вы не используете параметр WarningAction .

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

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

• $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 ответа приведены следующим образом:

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

См. также

• about_Preference_Variables
• Писать-Debug
• Write-Error
• Писать-Verbose
• Write-Warning