о_ОбщихПараметрах

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

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

Длинное описание

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

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

Общие параметры

-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 для текущей команды, задав значение $DebugPreferenceContinue.

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

-ErrorAction

Определяет, как командлет реагирует на неисключаемую ошибку из команды. Этот параметр переопределяет значение переменной $ErrorActionPreference для неисключающих ошибок, создаваемых командой или командлетом 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 не предотвращает завершение инструкций (например, отсутствующих данных, параметров, не допустимых или недостаточных разрешений) от остановки текущей инструкции. Однако если задано Stopзначение, он активирует неизменяемые ошибки до завершающихся сценарием ошибок, что делает их перехватываемыми try/catch. Дополнительные сведения о категориях ошибок см. в about_Error_Handling.

• Break Вводит отладчик при возникновении ошибки или возникновении исключения.
• Continue отображает сообщение об ошибке и продолжает выполнять команду. Continue — это значение по умолчанию.
• Ignore подавляет сообщение об ошибке и продолжает выполнять команду. В отличие от SilentlyContinueэтого, Ignore не добавляется не завершающаяся ошибка в автоматическую $Error переменную. Значение Ignore представлено в PowerShell 3.0.
• Inquire отображает сообщение об ошибке и запрашивает подтверждение перед продолжением выполнения. Это значение редко используется.
• SilentlyContinue подавляет сообщение об ошибке и продолжает выполнять команду.
• Stop отображает сообщение об ошибке и останавливает выполнение команды. Значение Stop вызывает неисключающую ошибку до конца ошибки путем ActionPreferenceStopExceptionсоздания ошибки. Затем ошибка может быть поймана блоком или trap операторомtry/catch.
• 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 в скрипте InformationActionWrite-Information значения отображаются в зависимости от значения InformationAction параметра. Дополнительные сведения см. в $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от этого, Ignore полностью забывает информационное сообщение; он не добавляет информационное сообщение в поток информации.
• Inquire отображает информационное сообщение, указанное в команде Write-Information , а затем задает вопрос о том, следует ли продолжить.
• Continue отображает информационное сообщение и продолжает работать.
• Suspend Не поддерживается в PowerShell 6 и более поздних версиях, так как он доступен только для рабочих процессов.
• SilentlyContinue не действует, так как информационное сообщение не отображается (по умолчанию), и сценарий продолжается без прерывания.

-InformationVariable

Представлено в PowerShell 5.0. При использовании общего параметра записи сведений InformationVariable хранятся в переменной, указанной параметром. Командлет PowerShell может записывать в поток записи сведений Information . Можно также использовать 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 В этом примере пять чисел передаются в первую ForEach-Object команду. Каждый элемент в конвейере хранится в переменной конвейера с именем $Temp.

Блок Process первой ForEach-Object команды передает элемент конвейера в нижестоящей ForEach-Object команде. Состояние переменных отображается на каждом шаге.

# Create a variable named $Temp
$Temp = 8
Get-Variable Temp | Format-Table

$InformationPreference = 'Continue'
Write-Information '-------------------------------------------------'
111,222,333,444,555 | ForEach-Object -PipelineVariable Temp -Begin {

  # Note that the newly create $Temp variable doesn't contain the value 8
  # assigned before the pipeline started and that $PSItem is empty in
  # the Begin block.
  Write-Information "Upstream (Begin):   PSItem = '$PSItem', Temp = '$Temp'"

} -Process {

  Write-Information "Upstream (Process): PSItem = '$PSItem', Temp = '$Temp'"
  return $PSItem

} | ForEach-Object -Process {

  Write-Information "`tDownstream: PSItem = '$PSItem', Temp = '$Temp'"

}
Write-Information '-------------------------------------------------'

# The $Temp variable is deleted when the pipeline finishes
Get-Variable Temp | Format-Table

Name                           Value
----                           -----
Temp                           8

-------------------------------------------------
Upstream (Begin):   PSItem = '', Temp = ''
Upstream (Process): PSItem = '111', Temp = ''
        Downstream: PSItem = '111', Temp = '111'
Upstream (Process): PSItem = '222', Temp = '111'
        Downstream: PSItem = '222', Temp = '222'
Upstream (Process): PSItem = '333', Temp = '222'
        Downstream: PSItem = '333', Temp = '333'
Upstream (Process): PSItem = '444', Temp = '333'
        Downstream: PSItem = '444', Temp = '444'
Upstream (Process): PSItem = '555', Temp = '444'
        Downstream: PSItem = '555', Temp = '555'
-------------------------------------------------

Name                           Value
----                           -----
Temp

Проблема 1. Использование [CmdletBinding()]функций CDXML, что позволяет параметру PipelineVariable .

Get-Partition -pv pvar

Однако при использовании PipelineVariable в Windows PowerShell версии 5.1 вы получите следующую ошибку.

Get-Partition : Cannot retrieve the dynamic parameters for the cmdlet.
Object reference not set to an instance of an object.

At line:1 char:1
+ get-partition -PipelineVariable pvar
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Get-Partition], ParameterBindingException
    + FullyQualifiedErrorId : GetDynamicParametersException,Get-Partition

Проблема 2. Если предыдущая команда не является командой CDXML, а подчиненный содержит любой тип команды, PipelineVariable остается как последний накопленный объект.

Get-CimInstance Win32_DiskDrive -pv pvar |
    ForEach-Object {
        Write-Host "Upstream: Disk $($pvar.Index)"
        return [pscustomobject]@{ DiskNumber = $_.Index }
    } | Get-Partition | ForEach-Object {
        Write-Host "Downstream: Disk $($pvar.Index)"
    }

Обратите внимание, что значение $pvar набора в последний объект в конвейере для второй ForEach-Object команды.

Upstream: Disk 1
Upstream: Disk 2
Upstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0

-ProgressAction

Определяет, как PowerShell реагирует на обновления хода выполнения, созданные скриптом, командлетом или поставщиком, например индикаторами хода выполнения, созданными командлетом Write-Progress . Командлет Write-Progress создает индикаторы хода выполнения, показывающие состояние команды. Параметр ProgressAction был добавлен в PowerShell 7.4.

Параметр ProgressAction принимает одно из значений ActionPreference перечисления: SilentlyContinue, Stop, Continue, Inquire, , IgnoreSuspendили 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

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

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

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

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

См. также

• о_переменных_предпочтений
• about_Error_Handling
• Write-Debug
• Write-Error
• Write-Verbose
• Write-Warning