о_общих_параметрах

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

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

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

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

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

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

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

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

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

• Debug (дб)
• 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

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

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

-Информационное Действие

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

-ИнформационнаяПеременная

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

$_ $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

-ПрогрессЭкшн

Определяет, как 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 является (значение по умолчанию).

-ПредупреждениеДействие

Определяет, как командлет реагирует на предупреждение из команды. 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

См. также

• о_переменных_предпочтений
• Писать-Debug
• Ошибка записи
• Писать-Verbose
• Предупреждение для записи