about_CommonParameters
Краткое описание
Описывает параметры, которые можно использовать с любым командлетом.
Подробное описание
Общие параметры — это набор параметров командлета, которые можно использовать с любым командлетом. Они реализованы PowerShell, а не разработчиком командлетов, и они автоматически доступны любому командлету.
Общие параметры можно использовать с любым командлетом, но они могут не влиять на все командлеты. Например, если командлет не создает подробные выходные данные, использование Verbose общего параметра не влияет.
Общие параметры также доступны в расширенных функциях, использующих атрибут КомандлетБининга или атрибут Параметра .
Несколько распространенных параметров переопределяют системные значения по умолчанию или предпочтения, заданные с помощью переменных предпочтений 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 — это перечисление со следующими значениями:
| Имя. | Значение |
|---|---|
Break |
6 |
Suspend |
5 |
Ignore |
4 |
Inquire |
3 |
Continue |
2 |
Stop |
1 |
SilentlyContinue |
0 |
Имя или значение можно использовать с параметром.
Помимо общих параметров, многие командлеты предлагают параметры устранения рисков. Командлеты, которые связаны с риском для системы или пользовательских данных, обычно предлагают эти параметры.
Параметры устранения рисков:
- 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 и более последующих версиях.
Примечание.
Параметр ErrorAction переопределяет, но не заменяет значение переменной $ErrorActionPreference при использовании параметра в команде для запуска скрипта или функции.
-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не действует, так как информационное сообщение не отображается (по умолчанию), и сценарий продолжается без прерывания.
Примечание.
Параметр InformationAction переопределяет, но не заменяет значение переменной $InformationAction предпочтения при использовании параметра в команде для запуска скрипта или функции.
-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
Примечание.
Переменная, созданная параметром OutVariable, является .[System.Collections.ArrayList]
-PipelineVariable
PipelineVariable позволяет получить доступ к последнему значению, передаваемому в следующий сегмент конвейера командой, которая использует этот параметр. Любая команда в конвейере может получить доступ к значению с помощью именованного PipelineVariable. Значение присваивается переменной при передаче в следующий сегмент конвейера. Это упрощает использование PipelineVariable , чем определенную временную переменную, которую может потребоваться назначить в нескольких расположениях.
В отличие $_ от того, $PSItemчто использование PipelineVariable позволяет любой команде конвейера получать доступ к значениям конвейера, переданным (и сохраненным) командами, отличными от непосредственно предыдущей команды. Команды конвейера могут получить доступ к последнему каналу значений при обработке следующего элемента, передаваемого через конвейер. Это позволяет команде передавать выходные данные в предыдущую команду (или сама по себе).
Примечание.
Расширенные функции могут содержать до трех блоков скриптов: begin, processи end. При использовании параметра PipelineVariable с расширенными функциями только значения из первого определенного блока скрипта назначаются переменной в качестве запуска функции. Дополнительные сведения см. в разделе "Дополнительные функции". PowerShell 7.2 исправляет это поведение.
Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Допустимые значения — это строки, аналогичные любым именам переменных.
Внимание
PipelineVariable область конвейеру, в котором он вызывается. Переменные за пределами конвейера, которые используют то же имя, очищаются перед выполнением конвейера. КонвейерVariable выходит из область при завершении конвейера. Если несколько команд в конвейере указывают один и тот же PipelineVariable , то существует только одна общая переменная. Эта переменная обновляется с последними выходными данными из команды, указывающей переменную.
Некоторые команды блокировки собирают все элементы конвейера перед созданием выходных данных, например Sort-Object или Select-Object -Last. Любой конвейерVariable , назначенный в команде перед такой командой блокировки, всегда содержит конечный элемент из предыдущей команды при использовании в команде после команды блокировки.
Ниже приведен пример работы 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 принимает одно из 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
Отображает подробные сведения об операции, выполняемой командой. Эта информация напоминает сведения в трассировке или в журнале транзакций. Этот параметр работает только в том случае, если команда создает подробное сообщение. Например, этот параметр работает, если команда содержит 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: 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отображает предупреждение и останавливает выполнение команды.
Примечание.
Параметр 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] ссылаться на определенные предупреждения, хранящиеся в переменной.
Примечание.
Переменная предупреждения содержит все предупреждения, созданные командой, включая предупреждения от вызовов вложенных функций или скриптов.
Описания параметров управления рисками
-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, которое приводит к значению переменной$WhatIfPreference1.
Например, следующая команда использует -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 ответа приведены следующим образом:
| Response | Результат |
|---|---|
Yes (Y) |
Выполните действие. |
Yes to All (A) |
Выполнение всех действий и отключение последующих действий Confirm |
| запросы для этой команды. | |
No (N): |
Не выполняйте действие. |
No to All (L): |
Не выполняйте никаких действий и не подавляйте последующие действия |
| Confirm запросы для этой команды. | |
Suspend (S): |
Приостанавливайте команду и создайте временный сеанс. |
Help (?) |
Отображение справки по этим параметрам. |
Параметр "Приостановка " помещает команду на удержание и создает временный вложенный сеанс, в котором можно работать до тех пор, пока не будете готовы выбрать 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
См. также
PowerShell
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по