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

about_Preference_Variables

  • Статья

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

Переменные, которые настраивают поведение PowerShell.

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

PowerShell включает набор переменных, позволяющих настроить его поведение. Эти переменные предпочтений работают так же, как параметры в системах на основе графического интерфейса.

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

В следующей таблице перечислены переменные предпочтения и их значения по умолчанию.

«Переменная» Значение по умолчанию
$ConfirmPreference High
$DebugPreference SilentlyContinue
$ErrorActionPreference Continue
$ErrorView ConciseView
$FormatEnumerationLimit 4
$InformationPreference SilentlyContinue
$LogCommandHealthEvent $false (не зарегистрировано)
$LogCommandLifecycleEvent $false (не зарегистрировано)
$LogEngineHealthEvent $true (зарегистрировано)
$LogEngineLifecycleEvent $true (зарегистрировано)
$LogProviderHealthEvent $true (зарегистрировано)
$LogProviderLifecycleEvent $true (зарегистрировано)
$MaximumHistoryCount 4096
$OFS Пробел (" ")
$OutputEncoding Объект UTF8Encoding.
$ProgressPreference Continue
$PSDefaultParameterValues @{} (пустая хэш-таблица)
$PSEmailServer $null (нет)
$PSModuleAutoLoadingPreference All
$PSNativeCommandArgumentPassing Windows в Windows, Standard не в Windows
$PSNativeCommandUseErrorActionPreference $false
$PSSessionApplicationName 'wsman'
$PSSessionConfigurationName 'http://schemas.microsoft.com/powershell/Microsoft.PowerShell'
$PSSessionOption Объект PSSessionOption.
$PSStyle Объект PSStyle.
$Transcript $null (нет)
$VerbosePreference SilentlyContinue
$WarningPreference Continue
$WhatIfPreference $false

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

  • $env:PSExecutionPolicyPreference
  • $env:PSModulePath

Примечание.

Изменения переменных предпочтений применяются только в области, в ней и любых дочерних областях. Например, можно ограничить влияние изменения переменной предпочтения на одну функцию или скрипт. Дополнительные сведения см. в about_Scopes.

Работа с переменными предпочтения

В этом документе описаны все переменные предпочтения.

Чтобы отобразить текущее значение определенной переменной предпочтения, введите имя переменной. Например, следующая команда отображает значение переменной $ConfirmPreference .

 $ConfirmPreference

High

Чтобы изменить значение переменной, используйте инструкцию назначения. Например, следующая инструкция изменяет $ConfirmPreference значение параметра на средний.

$ConfirmPreference = "Medium"

Заданные значения относятся к текущему сеансу PowerShell. Чтобы сделать переменные эффективными во всех сеансах PowerShell, добавьте их в профиль PowerShell. Дополнительные сведения см. в разделе about_Profiles.

Работа в удаленном режиме

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

Дополнительные сведения о удаленных командах см. в about_Remote.

$ConfirmPreference

Определяет, запрашивает ли PowerShell подтверждение перед выполнением командлета или функции автоматически.

Переменная $ConfirmPreference принимает одно из ConfirmImpact значений перечисления: High, Medium, Low или None.

Командлеты и функции назначаются риску высокого уровня, среднего или низкого уровня. Если значение переменной $ConfirmPreference меньше или равно риску, назначенному командлету или функции, PowerShell автоматически запрашивает подтверждение перед выполнением командлета или функции. Дополнительные сведения о назначении риска командлетам или функциям см . в about_Functions_CmdletBindingAttribute.

Если значение переменной $ConfirmPreference равно None, PowerShell никогда не будет автоматически запрашивать перед выполнением командлета или функции.

Чтобы изменить поведение подтверждения для всех командлетов и функций в сеансе, измените $ConfirmPreference значение переменной.

Чтобы переопределить $ConfirmPreference одну команду, используйте параметр подтверждения командлета или функции. Чтобы запросить подтверждение, используйте -Confirm. Чтобы отключить подтверждение, используйте -Confirm:$false.

Допустимые значения $ConfirmPreference:

  • Нет: PowerShell не запрашивает автоматически. Чтобы запросить подтверждение определенной команды, используйте параметр Confirm командлета или функции.
  • Низкий уровень: PowerShell запрашивает подтверждение перед выполнением командлетов или функций с низким, средним или высоким риском.
  • Средний: PowerShell запрашивает подтверждение перед выполнением командлетов или функций со средним или высоким риском.
  • Высокий уровень: PowerShell запрашивает подтверждение перед выполнением командлетов или функций с высоким риском.

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

PowerShell может автоматически запрашивать подтверждение перед выполнением действия. Например, если командлет или функция значительно влияют на систему для удаления данных или использования значительного количества системных ресурсов.

Remove-Item -Path C:\file.txt

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target "C:\file.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [?] Help (default is "Y"):

Оценка риска является атрибутом командлета или функции, известной как ConfirmImpact. Пользователи не могут изменить его.

Командлеты и функции, которые могут представлять риск для системы, имеют параметр Confirm , который можно использовать для запроса или подавления подтверждения для одной команды.

Большинство командлетов и функций сохраняют значение по умолчанию для Medium для ConfirmImpact. $ConfirmPreference По умолчанию задано значение High . Поэтому редко команды автоматически запрашивают подтверждение, если пользователи не указывают параметр Confirm . Чтобы расширить автоматическое подтверждение запроса на дополнительные командлеты и функции, задайте значение $ConfirmPreference "Средний " или "Низкий".

Примеры

В этом примере показан эффект значения по умолчанию переменной $ConfirmPreference High. Высокое значение подтверждает только командлеты и функции с высоким риском. Так как большинство командлетов и функций являются средним риском, они не будут автоматически подтверждены и Remove-Item удаляют файл. Добавление -Confirm в командную строку пользователя для подтверждения.

$ConfirmPreference

High

Remove-Item -Path C:\temp1.txt

Используется -Confirm для запроса подтверждения.

Remove-Item -Path C:\temp2.txt -Confirm

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target "C:\temp2.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All
[?] Help (default is "Y"):

В следующем примере показан эффект изменения значения $ConfirmPreference на средний. Так как большинство командлетов и функций являются средним риском, они автоматически подтверждаются. Чтобы отключить запрос подтверждения для одной команды, используйте параметр Confirm со значением $false.

$ConfirmPreference = "Medium"
Remove-Item -Path C:\temp2.txt

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target "C:\temp2.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All
[?] Help (default is "Y"):

Remove-Item -Path C:\temp3.txt -Confirm:$false

$DebugPreference

Определяет, как PowerShell реагирует на отладку сообщений, созданных скриптом, командлетом или поставщиком или командой в командной Write-Debug строке.

Переменная $DebugPreference принимает одно из ActionPreference значений перечисления: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend или Break.

Некоторые командлеты отображают сообщения отладки, которые обычно являются техническими сообщениями, предназначенными для программистов и специалистов по технической поддержке. По умолчанию сообщения отладки не отображаются, но вы можете отображать отладочные сообщения, изменив значение $DebugPreference.

Для отображения или скрытия сообщений отладки для определенной команды можно использовать общий параметр отладки командлета. Дополнительные сведения см. в разделе about_CommonParameters.

Допустимы следующие значения.

  • Разрыв . Введите отладчик при возникновении ошибки или при возникновении исключения.
  • Остановка. Отображает сообщение отладки и останавливает выполнение. Записывает ошибку в консоль.
  • Запрос. Отображает сообщение отладки и спрашивает, хотите ли вы продолжить.
  • Продолжить. Отображает сообщение отладки и продолжает выполнение.
  • SilentlyContinue: (по умолчанию) Нет эффекта. Сообщение отладки не отображается, и выполнение продолжается без прерывания.

Добавление общего параметра отладки в команду, когда команда настроена для создания сообщения отладки, изменяет значение переменной $DebugPreference на "Продолжить".

Примеры

В следующих примерах показано, как изменить значения $DebugPreference Write-Debug при вводе команды в командной строке. Это изменение влияет на все сообщения отладки, включая сообщения, созданные командлетами и скриптами. В примерах показан параметр отладки , который отображает или скрывает сообщения отладки, связанные с одной командой.

В этом примере показан эффект значения переменной $DebugPreference по умолчанию, SilentlyContinue. По умолчанию Write-Debug сообщение отладки командлета не отображается и обработка продолжается. Если используется параметр отладки, он переопределяет предпочтение одной команды. Отображается сообщение отладки.

$DebugPreference

SilentlyContinue

Write-Debug -Message "Hello, World"

Write-Debug -Message "Hello, World" -Debug

DEBUG: Hello, World

В этом примере показан эффект значения $DebugPreference "Продолжить ". Отображается сообщение отладки, и команда продолжает обрабатываться.

$DebugPreference = "Continue"
Write-Debug -Message "Hello, World"

DEBUG: Hello, World

В этом примере используется параметр отладки со значением $false для подавления сообщения для одной команды. Сообщение отладки не отображается.

Write-Debug -Message "Hello, World" -Debug:$false

В этом примере показан эффект $DebugPreference установки значения Stop . Отображается сообщение отладки, и команда остановлена.

$DebugPreference = "Stop"
Write-Debug -Message "Hello, World"

DEBUG: Hello, World
Write-Debug : The running command stopped because the preference variable
 "DebugPreference" or common parameter is set to Stop: Hello, World
At line:1 char:1
+ Write-Debug -Message "Hello, World"

В этом примере используется параметр отладки со значением $false для подавления сообщения для одной команды. Сообщение отладки не отображается и обработка не останавливается.

Write-Debug -Message "Hello, World" -Debug:$false

В этом примере показан эффект $DebugPreference задания значения Inquire . Отображается сообщение отладки, и пользователю предлагается подтверждение.

$DebugPreference = "Inquire"
Write-Debug -Message "Hello, World"

DEBUG: Hello, World

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):

В этом примере используется параметр отладки со значением $false для подавления сообщения для одной команды. Сообщение отладки не отображается и продолжается обработка.

Write-Debug -Message "Hello, World" -Debug:$false

$ErrorActionPreference

Определяет, как PowerShell реагирует на неустранимую ошибку, ошибку, которая не останавливает обработку командлета. Например, в командной строке или в скрипте, командлете или поставщике, таких как ошибки, созданные командлетом Write-Error .

Переменная $ErrorActionPreference принимает одно из ActionPreference значений перечисления: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend или Break.

Общий параметр ErrorAction командлета можно использовать для переопределения предпочтений определенной команды.

Допустимы следующие значения.

  • Разрыв . Введите отладчик при возникновении ошибки или при возникновении исключения.
  • Продолжить: (по умолчанию) Отображает сообщение об ошибке и продолжает выполняться.
  • Игнорировать: подавляет сообщение об ошибке и продолжает выполнять команду. Значение "Игнорировать" предназначено для использования для каждой команды, а не для использования в качестве сохраненных предпочтений. Игнорировать не является допустимым значением переменной $ErrorActionPreference .
  • Запрос. Отображает сообщение об ошибке и спрашивает, хотите ли продолжить.
  • SilentlyContinue: Нет эффекта. Сообщение об ошибке не отображается, и выполнение продолжается без прерывания.
  • Остановка: отображает сообщение об ошибке и останавливает выполнение. В дополнение к созданной ошибке значение Stop создает объект ActionPreferenceStopException в поток ошибок.
  • Приостановка: автоматически приостанавливает задание рабочего процесса, чтобы разрешить дальнейшее исследование. После изучения рабочий процесс можно возобновить. Значение "Приостановка" предназначено для использования каждой команды, а не для использования в качестве сохраненных предпочтений. Приостановка не является допустимым значением переменной $ErrorActionPreference .

$ErrorActionPreferenceи параметр ErrorAction не влияют на то, как PowerShell реагирует на завершающие ошибки, которые останавливают обработку командлетов. Дополнительные сведения об общем параметре ErrorAction см. в about_CommonParameters.

Многие собственные команды выполняют запись в stderr в качестве альтернативного потока для сохранения дополнительных сведений. Такое поведение может запутать пользователя при просмотре ошибок или же дополнительная выходная информация может быть утрачена для пользователя, если для $ErrorActionPreference настроено состояние, блокирующее вывод данных.

Начиная с PowerShell 7.2 записи об ошибках, перенаправленные из собственных команд, например при использовании операторов перенаправления (2>&1), не записываются $Error в переменную, а переменная $ErrorActionPreference предпочтения не влияет на перенаправленные выходные данные.

PowerShell 7.3 добавил экспериментальную функцию, которая позволяет управлять обработкой сообщений, записанных stderr в них.

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

Примеры

В этих примерах показан эффект различных значений переменной $ErrorActionPreference . Параметр ErrorAction используется для переопределения $ErrorActionPreference значения.

В этом примере по умолчанию отображается $ErrorActionPreference значение " Продолжить". Возникает несрочная ошибка. Отображается сообщение и продолжается обработка.

# Change the ErrorActionPreference to 'Continue'
$ErrorActionPreference = 'Continue'
# Generate a non-terminating error and continue processing the script.
Write-Error -Message  'Test Error' ; Write-Host 'Hello World'

Write-Error: Test Error
Hello World

В этом примере показано $ErrorActionPreference значение по умолчанию, Inquire. Возникает ошибка и отображается запрос на действие.

# Change the ErrorActionPreference to 'Inquire'
$ErrorActionPreference = 'Inquire'
Write-Error -Message 'Test Error' ; Write-Host 'Hello World'

Confirm
Test Error
[Y] Yes  [A] Yes to All  [H] Halt Command  [S] Suspend  [?] Help (default is "Y"):

В этом примере показано значение $ErrorActionPreference "SilentlyContinue". Сообщение об ошибке подавляется.

# Change the ErrorActionPreference to 'SilentlyContinue'
$ErrorActionPreference = 'SilentlyContinue'
# Generate an error message
Write-Error -Message 'Test Error' ; Write-Host 'Hello World'
# Error message is suppressed and script continues processing

Hello World

В этом примере показано, $ErrorActionPreference как установить значение Stop. В нем также показан дополнительный объект, созданный переменной $Error .

# Change the ErrorActionPreference to 'Stop'
$ErrorActionPreference = 'Stop'
# Error message is generated and script stops processing
Write-Error -Message 'Test Error' ; Write-Host 'Hello World'

# Show the ActionPreferenceStopException and the error generated
$Error[0]
$Error[1]

Write-Error: Test Error

ErrorRecord                 : Test Error
WasThrownFromThrowStatement : False
TargetSite                  : System.Collections.ObjectModel.Collection`1[System.Management.Automation.PSObject]
                              Invoke(System.Collections.IEnumerable)
StackTrace                  :    at System.Management.Automation.Runspaces.PipelineBase.Invoke(IEnumerable input)
                                 at Microsoft.PowerShell.Executor.ExecuteCommandHelper(Pipeline tempPipeline,
                              Exception& exceptionThrown, ExecutionOptions options)
Message                     : The running command stopped because the preference variable "ErrorActionPreference" or
                              common parameter is set to Stop: Test Error
Data                        : {System.Management.Automation.Interpreter.InterpretedFrameInfo}
InnerException              :
HelpLink                    :
Source                      : System.Management.Automation
HResult                     : -2146233087

Write-Error: Test Error

$ErrorView

Определяет формат отображения сообщений об ошибках в PowerShell.

Переменная $ErrorView принимает одно из значений ErrorView перечисления: NormalView, CategoryView или ConciseView.

Допустимы следующие значения.

  • Краткий обзор: (по умолчанию) предоставляет краткое сообщение об ошибке и рефакторинг представления для расширенных построителей модулей. По состоянию на PowerShell 7.2, если ошибка находится в командной строке или модуле скрипта, выходные данные являются сообщением об ошибке одной строки. В противном случае вы получите многостроочное сообщение об ошибке, содержащее ошибку и указатель на ошибку, показывающую, где она происходит в этой строке. Если терминал поддерживает виртуальный терминал, то коды цветов ANSI используются для выделения цветового акцента. Цвет акцента можно изменить по $Host.PrivateData.ErrorAccentColorадресу. Используйте Get-Error командлет для комплексного подробного представления полной ошибки, включая внутренние исключения.

    Краткое представление Было добавлено в PowerShell 7.

  • NormalView: подробное представление, предназначенное для большинства пользователей. Состоит из описания ошибки и имени объекта, связанного с ошибкой.

  • CategoryView: краткое структурированное представление, предназначенное для рабочих сред. Используется следующий формат:

    {Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

Дополнительные сведения о полях в CategoryView см. в классе ErrorCategoryInfo.

Примеры

В этом примере показано, как отображается ошибка, если значение $ErrorView по умолчанию — ConciseView. Get-ChildItem используется для поиска несуществующего каталога.

Get-ChildItem -path 'C:\NoRealDirectory'

Get-ChildItem: Can't find path 'C:\NoRealDirectory' because it doesn't exist.

В этом примере показано, как отображается ошибка, если значение $ErrorView по умолчанию — ConciseView. Script.ps1 выполняется и вызывает ошибку из Get-Item инструкции.

./Script.ps1

Get-Item: C:\Script.ps1
Line |
  11 | Get-Item -Path .\stuff
     | ^ Can't find path 'C:\demo\stuff' because it doesn't exist.

В этом примере показано, как отображается ошибка при изменении значения $ErrorView в NormalView. Get-ChildItem используется для поиска несуществующего файла.

Get-ChildItem -Path C:\nofile.txt

Get-ChildItem : Can't find path 'C:\nofile.txt' because it doesn't exist.
At line:1 char:1
+ Get-ChildItem -Path C:\nofile.txt

В этом примере показано, как появляется та же ошибка при изменении значения $ErrorView в CategoryView.

$ErrorView = "CategoryView"
Get-ChildItem -Path C:\nofile.txt

ObjectNotFound: (C:\nofile.txt:String) [Get-ChildItem], ItemNotFoundException

В этом примере показано, что значение $ErrorView влияет только на отображение ошибки. Он не изменяет структуру объекта ошибки, хранящегося в автоматической переменной $Error . Сведения об автоматической переменной $Error см. в about_automatic_variables.

Следующая команда принимает объект ErrorRecord , связанный с последней ошибкой в массиве ошибок, элемент 0 и форматирует свойства объекта в списке.

$Error[0] | Format-List -Property * -Force

PSMessageDetails      :
Exception             : System.Management.Automation.ItemNotFoundException:
                          Cannot find path 'C:\nofile.txt' because it does
                          not exist.
                        at System.Management.Automation.SessionStateInternal.
                          GetChildItems(String path, Boolean recurse, UInt32
                          depth, CmdletProviderContext context)
                        at System.Management.Automation.ChildItemCmdlet
                          ProviderIntrinsics.Get(String path, Boolean
                          recurse, UInt32 depth, CmdletProviderContext context)
                        at Microsoft.PowerShell.Commands.GetChildItemCommand.
                          ProcessRecord()
TargetObject          : C:\nofile.txt
CategoryInfo          : ObjectNotFound: (C:\nofile.txt:String) [Get-ChildItem],
                          ItemNotFoundException
FullyQualifiedErrorId : PathNotFound,
                          Microsoft.PowerShell.Commands.GetChildItemCommand
ErrorDetails          :
InvocationInfo        : System.Management.Automation.InvocationInfo
ScriptStackTrace      : at <ScriptBlock>, <No file>: line 1
PipelineIterationInfo : {0, 1}

$FormatEnumerationLimit

Определяет количество перечисленных элементов, включенных в дисплей. Эта переменная не влияет на базовые объекты, только отображение. Если значение $FormatEnumerationLimit меньше числа перечисленных элементов, PowerShell добавляет многоточие (...) для указания элементов, которые не отображаются.

Допустимые значения: целые числа (Int32)

Значение по умолчанию: 4

Примеры

В этом примере показано, как использовать $FormatEnumerationLimit переменную для улучшения отображения перечисленных элементов.

Команда в этом примере создает таблицу, в которой перечислены все службы, работающие на компьютере, в двух группах: один для запуска служб и один для остановленных служб. Он использует Get-Service команду для получения всех служб, а затем отправляет результаты через конвейер Group-Object в командлет, который группирует результаты по состоянию службы.

Результатом является таблица, которая содержит состояние в столбце "Имя " и процессы в столбце "Группа ". Чтобы изменить метки столбцов, используйте хэш-таблицу, см . about_Hash_Tables. Дополнительные сведения см. в примерах в format-Table.

Найдите текущее значение $FormatEnumerationLimit.

$FormatEnumerationLimit

4

Вывод списка всех служб, сгруппированных по состоянию. Существует не более четырех служб, перечисленных в столбце "Группа " для каждого состояния, так как $FormatEnumerationLimit имеет значение 4.

Get-Service | Group-Object -Property Status

Count  Name       Group
-----  ----       -----
60     Running    {AdtAgent, ALG, Ati HotKey Poller, AudioSrv...}
41     Stopped    {Alerter, AppMgmt, aspnet_state, ATI Smart...}

Чтобы увеличить число перечисленных элементов, увеличьте значение $FormatEnumerationLimit до 1000. Использование Get-Service и Group-Object отображение служб.

$FormatEnumerationLimit = 1000
Get-Service | Group-Object -Property Status

Count  Name       Group
-----  ----       -----
60     Running    {AdtAgent, ALG, Ati HotKey Poller, AudioSrv, BITS, CcmExec...
41     Stopped    {Alerter, AppMgmt, aspnet_state, ATI Smart, Browser, CiSvc...

Используйте Format-Table параметр оболочки для отображения списка служб.

Get-Service | Group-Object -Property Status | Format-Table -Wrap

Count  Name       Group
-----  ----       -----
60     Running    {AdtAgent, ALG, Ati HotKey Poller, AudioSrv, BITS, CcmExec,
                  Client for NFS, CryptSvc, DcomLaunch, Dhcp, dmserver,
                  Dnscache, ERSvc, Eventlog, EventSystem, FwcAgent, helpsvc,
                  HidServ, IISADMIN, InoRPC, InoRT, InoTask, lanmanserver,
                  lanmanworkstation, LmHosts, MDM, Netlogon, Netman, Nla,
                  NtLmSsp, PlugPlay, PolicyAgent, ProtectedStorage, RasMan,
                  RemoteRegistry, RpcSs, SamSs, Schedule, seclogon, SENS,
                  SharedAccess, ShellHWDetection, SMT PSVC, Spooler,
                  srservice, SSDPSRV, stisvc, TapiSrv, TermService, Themes,
                  TrkWks, UMWdf, W32Time, W3SVC, WebClient, winmgmt, wscsvc,
                  wuauserv, WZCSVC, zzInterix}

41     Stopped    {Alerter, AppMgmt, aspnet_state, ATI Smart, Browser, CiSvc,
                  ClipSrv, clr_optimization_v2.0.50727_32, COMSysApp,
                  CronService, dmadmin, FastUserSwitchingCompatibility,
                  HTTPFilter, ImapiService, Mapsvc, Messenger, mnmsrvc,
                  MSDTC, MSIServer, msvsmon80, NetDDE, NetDDEdsdm, NtmsSvc,
                  NVSvc, ose, RasAuto, RDSessMgr, RemoteAccess, RpcLocator,
                  SCardSvr, SwPrv, SysmonLog, TlntSvr, upnphost, UPS, VSS,
                  WmdmPmSN, Wmi, WmiApSrv, xmlprov}

$InformationPreference

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

Переменная $InformationPreference принимает одно из ActionPreference значений перечисления: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend или Break.

Допустимы следующие значения.

  • Разрыв . Введите отладчик при записи в поток сведений.
  • Остановка. Останавливает команду или скрипт при вхождании Write-Information команды.
  • Запрос. Отображает информационное сообщение, указанное в команде Write-Information , а затем спрашивает, хотите ли продолжить.
  • Продолжить: отображает информационное сообщение и продолжает выполняться.
  • SilentlyContinue: (по умолчанию) Нет эффекта. Информационные сообщения не отображаются, и сценарий продолжается без прерывания.

событие $Log*

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

Переменные предпочтений log*Event :

  • $LogCommandHealthEvent: регистрирует ошибки и исключения в инициализации и обработке команд. Значение по умолчанию — $false (не зарегистрировано).
  • $LogCommandLifecycleEvent: регистрирует начальные и остановки команд и конвейеры команд и исключения безопасности при обнаружении команд. Значение по умолчанию — $false (не зарегистрировано).
  • $LogEngineHealthEvent: регистрирует ошибки и сбои сеансов. Значение по умолчанию — $true (зарегистрировано).
  • $LogEngineLifecycleEvent: регистрирует открытие и закрытие сеансов. Значение по умолчанию — $true (зарегистрировано).
  • $LogProviderHealthEvent: ошибки поставщика журналов, такие как ошибки чтения и записи, ошибки подстановки и ошибки вызова. Значение по умолчанию — $true (зарегистрировано).
  • $LogProviderLifecycleEvent: журналы, добавляющие и удаляющие поставщики PowerShell. Значение по умолчанию — $true (зарегистрировано). Сведения о поставщиках PowerShell см. в about_Providers.

Чтобы включить событие Log*, введите переменную со значением $true, например:

$LogCommandLifeCycleEvent = $true

Чтобы отключить тип события, введите переменную со значением $false, например:

$LogCommandLifeCycleEvent = $false

События, которые вы включаете, эффективны только для текущей консоли PowerShell. Чтобы применить конфигурацию ко всем консоли, сохраните параметры переменной в профиле PowerShell. Дополнительные сведения см. в разделе about_Profiles.

$MaximumHistoryCount

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

Допустимые значения: 1 – 32768 (Int32)

По умолчанию: 4096

Чтобы определить количество команд, сохраненных в журнале команд, введите следующее:

(Get-History).Count

Чтобы просмотреть команды, сохраненные в журнале сеансов, используйте Get-History командлет. Дополнительные сведения см. в about_History.

$OFS

Разделитель полей вывода (OFS) задает символ, разделяющий элементы массива, преобразованного в строку.

Допустимые значения: любая строка.

По умолчанию: пробел

По умолчанию переменная не существует, $OFS а разделитель выходных файлов — это пространство, но вы можете добавить эту переменную и задать ее для любой строки. Вы можете изменить значение $OFS в сеансе, введя $OFS="<value>"текст.

Примечание.

Если вы ожидаете значение по умолчанию пробела (" ") в скрипте, модуле или выходных данных конфигурации, убедитесь, что $OFS значение по умолчанию не было изменено в другом месте кода.

Примеры

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

$array = 1,2,3,4
[string]$array

1 2 3 4

Чтобы изменить разделитель, добавьте $OFS переменную, назначив ему значение. Переменная должна быть названа $OFS.

$OFS = "+"
[string]$array

1+2+3+4

Чтобы восстановить поведение по умолчанию, можно назначить пробел (" ") значению $OFS или удалить переменную. Следующие команды удаляют переменную, а затем проверяют, является ли разделитель пробелом.

Remove-Variable OFS
[string]$array

1 2 3 4

$OutputEncoding

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

Примечание.

В большинстве сценариев значение должно $OutputEncoding соответствовать значению [Console]::InputEncoding.

Допустимые значения: объекты, производные от класса кодировки, например ASCIIEncoding, UTF7Encoding, UTF8Encoding, UTF32Encoding и UnicodeEncoding.

По умолчанию: объект UTF8Encoding .

Примеры

Первая команда находит значение $OutputEncoding. Так как значение является объектом кодирования, отображается только его свойство EncodingName .

$OutputEncoding.EncodingName

Остальные примеры используют следующий скрипт PowerShell, сохраненный для hexdump.ps1 иллюстрации $OutputEncodingповедения.

$inputStream = [Console]::OpenStandardInput()
try {
    $buffer = [byte[]]::new(1024)
    $read = $inputStream.Read($buffer, 0, $buffer.Length)
    Format-Hex -InputObject $buffer -Count $read
} finally {
    $inputStream.Dispose()
}

В следующем примере показано, как строковое значение café закодировано в байты при вводе в hexdump.ps1 созданный выше объект. В нем показано, что строковое значение закодировано с помощью схемы UTF8Encoding.

'café' | pwsh -File ./hexdump.ps1

   Label: Byte[] (System.Byte[]) <28873E25>

          Offset Bytes                                           Ascii
                 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
          ------ ----------------------------------------------- -----
0000000000000000 63 61 66 C3 A9 0D 0A                            caf�

В следующем примере показано, как байты изменяются при изменении кодировки в ЮникодEncoding.

$OutputEncoding = [System.Text.Encoding]::Unicode
'café' | pwsh -File ./hexdump.ps1

   Label: Byte[] (System.Byte[]) <515A7DC3>

          Offset Bytes                                           Ascii
                 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
          ------ ----------------------------------------------- -----
0000000000000000 FF FE 63 00 61 00 66 00 E9 00 0D 00 0A 00       ÿþc a f é � �

$ProgressPreference

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

Переменная $ProgressPreference принимает одно из ActionPreference значений перечисления: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend или Break.

Допустимы следующие значения.

  • Разрыв . Введите отладчик при записи в поток Progress.
  • Остановка: не отображает индикатор хода выполнения. Вместо этого отображается сообщение об ошибке и останавливается выполнение.
  • Запрос. Не отображает индикатор хода выполнения. Запрашивает разрешение на продолжение. При ответе на Y запрос или Aотображается индикатор хода выполнения.
  • Продолжить: (по умолчанию) Отображает индикатор хода выполнения и продолжает выполнение.
  • SilentlyContinue: выполняет команду, но не отображает индикатор выполнения.

$PSDefaultParameterValues

Задает значения по умолчанию для параметров командлетов и расширенных функций. Значением $PSDefaultParameterValues является хэш-таблица, в которой ключ состоит из имени командлета и имени параметра, разделенного двоеточием (:). Это настраиваемое значение по умолчанию.

$PSDefaultParameterValues появилась в PowerShell 3.0.

Дополнительные сведения об этой переменной предпочтения см. в about_Parameters_Default_Values.

$PSEmailServer

Указывает сервер электронной почты по умолчанию, используемый для отправки сообщений электронной почты. Эта переменная предпочтения используется командлетами, отправляющими сообщение электронной почты, например командлетом Send-MailMessage .

$PSModuleAutoloadingPreference

Включает и отключает автоматическое импорт модулей в сеансе. Переменная $PSModuleAutoloadingPreference по умолчанию не существует. Поведение по умолчанию, если переменная не определена так же, как $PSModuleAutoloadingPreference = 'All'.

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

Переменная $PSModuleAutoloadingPreference принимает одно из значений PSModuleAutoLoadingPreference перечисления:

  • All: модули импортируются автоматически при первом использовании.
  • ModuleQualified: модули импортируются автоматически, только если пользователь использует имя команды в модуле. Например, если типы MyModule\MyCommandпользователей, PowerShell импортирует модуль MyModule .
  • None: отключает автоматический импорт модулей. Чтобы импортировать модуль, используйте Import-Module командлет.

Дополнительные сведения о автоматическом импорте модулей см. в about_Modules.

$PSNativeCommandArgumentPassing

PowerShell 7.3 изменил способ анализа командной строки для собственных команд. Новая $PSNativeCommandArgumentPassing переменная предпочтения управляет этим поведением.

Внимание

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

Автоматическая переменная $PSNativeCommandArgumentPassing позволяет выбрать поведение во время выполнения. Возможные значения: Legacy, Standard и Windows. Legacy является историческим поведением.

Переменная $PSNativeCommandArgumentPassing определяется по умолчанию, но значение зависит от платформы.

  • В Windows для параметра задано значение Windows.
  • На платформах, отличных от Windows, для параметра задано Standardзначение .
  • Если вы удалили $PSNativeCommandArgumentPassing переменную, PowerShell использует Standard поведение.

Поведение Windows и Standard режим одинаковы, Windows за исключением режима PowerShell использует Legacy поведение аргумента, передаваемого при выполнении следующих файлов.

  • cmd.exe
  • cscript.exe
  • find.exe
  • sqlcmd.exe
  • wscript.exe
  • Файлы заканчиваются следующими:
    • .bat
    • .cmd
    • .js
    • .vbs
    • .wsf

$PSNativeCommandArgumentPassing Если задано значение "ЛибоLegacy"Standard, средство синтаксического анализа не проверяет наличие этих файлов. Примеры нового поведения см. в about_Parsing.

PowerShell 7.3 также добавил возможность трассировки привязки параметров для собственных команд. Дополнительные сведения см. в разделе Trace-Command.

$PSNativeCommandUseErrorActionPreference

Если $PSNativeCommandUseErrorActionPreference есть $true, собственные команды с ненулевыми кодами выхода выдают ошибки в соответствии $ErrorActionPreferenceс.

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

& {
    # Disable $PSNativeCommandUseErrorActionPreference for this scriptblock
    $PSNativeCommandUseErrorActionPreference = $false
    robocopy.exe D:\reports\operational "\\reporting\ops" CY2022Q4.md
    if ($LASTEXITCODE -gt 8) {
        throw "robocopy failed with exit code $LASTEXITCODE"
    }
}

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

$PSSessionApplicationName

Указывает имя приложения по умолчанию для удаленной команды, использующую веб-службы для управления (WS-Management). Дополнительные сведения см. в разделе о удаленном управлении Windows.

Системное имя WSMANприложения по умолчанию, но для изменения значения по умолчанию можно использовать эту переменную предпочтения.

Имя приложения — это последний узел в URI подключения. Например, имя приложения в следующем примере универсального кода ресурса (URI) — WSMANэто .

http://Server01:8080/WSMAN

Имя приложения по умолчанию используется, если удаленная команда не указывает URI подключения или имя приложения.

Служба WinRM использует имя приложения для выбора прослушивателя для обслуживания запроса на подключение. Значение параметра должно соответствовать значению свойства URLPrefix прослушивателя на удаленном компьютере.

Чтобы переопределить системное значение по умолчанию и значение этой переменной, а также выбрать другое имя приложения для определенного сеанса, используйте параметры ConnectionURI или ApplicationName для командлетов New-PSSession, ВВОД-PSSession или Invoke-Command.

Переменная $PSSessionApplicationName предпочтения устанавливается на локальном компьютере, но указывает прослушиватель на удаленном компьютере. Если указанное имя приложения не существует на удаленном компьютере, команда для установки сеанса завершается ошибкой.

$PSSessionConfigurationName

Указывает конфигурацию сеанса по умолчанию, которая используется для создания новых сеансов в текущем сеансе.

Эта переменная предпочтения устанавливается на локальном компьютере, но указывает конфигурацию сеанса, расположенную на удаленном компьютере.

Значение переменной $PSSessionConfigurationName — полный URI ресурса.

Значение http://schemas.microsoft.com/PowerShell/microsoft.PowerShell по умолчанию указывает конфигурацию сеанса Microsoft.PowerShell на удаленном компьютере.

Если указать только имя конфигурации, предопределен следующий универсальный код ресурса (URI) схемы:

http://schemas.microsoft.com/PowerShell/

Можно переопределить значение по умолчанию и выбрать другую конфигурацию сеанса для определенного Enter-PSSessionNew-PSSessionсеанса с помощью параметра ConfigurationName командлетов или Invoke-Command командлетов.

Вы можете изменить значение этой переменной в любое время. При этом помните, что выбранная конфигурация сеанса должна существовать на удаленном компьютере. Если это не так, команда для создания сеанса, использующего конфигурацию сеанса, завершается сбоем.

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

$PSSessionOption

Устанавливает значения по умолчанию для расширенных параметров пользователя в удаленном сеансе. Эти параметры переопределяют системные значения по умолчанию для параметров сеанса.

Переменная $PSSessionOption содержит объект PSSessionOption . Дополнительные сведения см. в разделе System.Management.Automation.Remoting.PSSessionOption. Каждое свойство объекта представляет параметр сеанса. Например, свойство NoCompression превращает сжатие данных во время сеанса.

По умолчанию переменная содержит объект PSSessionOption со значениями по умолчанию $PSSessionOption для всех параметров, как показано ниже.

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : None
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
IncludePortInSPN                  : False
OutputBufferingMode               : None
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         : 209715200
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : -00:00:00.0010000

Описание этих параметров и дополнительные сведения см. в разделе New-PSSessionOption. Дополнительные сведения о удаленных командах и сеансах см. в about_Remote и about_PSSessions.

Чтобы изменить значение переменной $PSSessionOption предпочтения, используйте New-PSSessionOption командлет для создания объекта PSSessionOption со значениями параметров, которые вы предпочитаете. Сохраните выходные данные в переменной с именем $PSSessionOption.

$PSSessionOption = New-PSSessionOption -NoCompression

Чтобы использовать $PSSessionOption переменную предпочтения в каждом сеансе PowerShell, добавьте New-PSSessionOption команду, которая создает $PSSessionOption переменную в профиль PowerShell. Дополнительные сведения см. в разделе about_Profiles.

Настраиваемые параметры для определенного удаленного сеанса можно задать. Заданные параметры имеют приоритет над системными значениями по умолчанию и значением переменной $PSSessionOption предпочтения.

Чтобы задать параметры пользовательского сеансаNew-PSSessionOption, используйте командлет для создания объекта PSSessionOption. Затем используйте объект PSSessionOption в качестве значения параметра SessionOption в командлетах, создающих сеанс, например New-PSSession, Enter-PSSessionи Invoke-Command.

$PSStyle

По состоянию на PowerShell 7.2 теперь можно получить доступ к автоматической $PSStyle переменной для просмотра и изменения отрисовки выходных данных строки ANSI. $PSStyle — это экземпляр класса PSStyle . Члены этого класса определяют строки, содержащие escape-последовательности ANSI, которые управляют отрисовкой текста в терминале.

Базовые элементы возвращают строки escape-последовательностей ANSI, сопоставленные с их именами. Значения можно настраивать. Имена свойств упрощают создание украшенных строк с помощью завершения вкладки. Например:

"$($PSStyle.Background.BrightCyan)Power$($PSStyle.Underline)$($PSStyle.Bold)Shell$($PSStyle.Reset)"

Элементы фона и переднего плана также имеют FromRgb() метод для указания 24-разрядного цвета.

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

$Transcript

Используется для Start-Transcript указания имени и расположения файла расшифровки. Если значение параметра Path не указано, Start-Transcript используется путь в значении глобальной переменной $Transcript . Если вы не создали эту переменную, Start-Transcript сохраните расшифровки в следующем расположении с помощью имени по умолчанию:

  • В Windows: $HOME\Documents
  • В Linux или macOS: $HOME

Имя файла по умолчанию: PowerShell_transcript.<computername>.<random>.<timestamp>.txt

$VerbosePreference

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

По умолчанию подробные сообщения не отображаются, но это поведение можно изменить, изменив значение $VerbosePreference.

Переменная $VerbosePreference принимает одно из ActionPreference значений перечисления: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend или Break.

Допустимы следующие значения.

  • Разрыв . Введите отладчик при записи в поток Подробных сведений.
  • Остановка. Отображает подробное сообщение и сообщение об ошибке, а затем останавливает выполнение.
  • Запрос. Отображает подробное сообщение, а затем отображает запрос, который спрашивает, хотите ли вы продолжить.
  • Продолжить. Отображает подробное сообщение, а затем продолжает выполнение.
  • SilentlyContinue: (по умолчанию) не отображает подробное сообщение. Продолжает выполняться.

Вы можете использовать подробный общий параметр командлета для отображения или скрытия подробных сообщений для определенной команды. Дополнительные сведения см. в разделе about_CommonParameters.

Примеры

В этих примерах показан эффект различных значений $VerbosePreference и параметра Verbose для переопределения значения предпочтения.

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

Write-Verbose -Message "Verbose message test."

Если используется подробный параметр, сообщение записывается.

Write-Verbose -Message "Verbose message test." -Verbose

VERBOSE: Verbose message test.

В этом примере показан эффект значения Continue . Переменная $VerbosePreference имеет значение "Продолжить" , и отображается сообщение.

$VerbosePreference = "Continue"
Write-Verbose -Message "Verbose message test."

VERBOSE: Verbose message test.

В этом примере используется параметр Verbose со значением$false, которое переопределяет значение Continue. Сообщение не отображается.

Write-Verbose -Message "Verbose message test." -Verbose:$false

В этом примере показан эффект значения Stop . Переменная $VerbosePreference имеет значение Stop и отображается сообщение. Команда остановлена.

$VerbosePreference = "Stop"
Write-Verbose -Message "Verbose message test."

VERBOSE: Verbose message test.
Write-Verbose : The running command stopped because the preference variable
  "VerbosePreference" or common parameter is set to Stop: Verbose message test.
At line:1 char:1
+ Write-Verbose -Message "Verbose message test."

В этом примере используется параметр Verbose со значением$false, которое переопределяет значение Stop. Сообщение не отображается.

Write-Verbose -Message "Verbose message test." -Verbose:$false

В этом примере показан эффект значения Inquire . Переменная $VerbosePreference имеет значение Inquire. Отображается сообщение, и пользователю предлагается подтверждение.

$VerbosePreference = "Inquire"
Write-Verbose -Message "Verbose message test."

VERBOSE: Verbose message test.

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):

В этом примере используется подробный параметр со значением$false, которое переопределяет значение Inquire. Пользователь не запрашивается, и сообщение не отображается.

Write-Verbose -Message "Verbose message test." -Verbose:$false

$WarningPreference

Определяет способ реагирования PowerShell на предупреждающие сообщения, созданные скриптом, командлетом или поставщиком, такими как сообщения, созданные командлетом Write-Warning .

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

Переменная $WarningPreference принимает одно из ActionPreference значений перечисления: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend или Break.

Допустимы следующие значения.

  • Разрыв . Введите отладчик при записи предупреждения.
  • Остановка. Отображает предупреждающее сообщение и сообщение об ошибке, а затем останавливает выполнение.
  • Запрос. Отображает предупреждение, а затем запрашивает разрешение на продолжение.
  • Продолжить: (по умолчанию) Отображает предупреждение, а затем продолжает выполняться.
  • SilentlyContinue: не отображает предупреждение. Продолжает выполняться.

Вы можете использовать общий параметр WarningAction командлета, чтобы определить, как PowerShell реагирует на предупреждения из определенной команды. Дополнительные сведения см. в разделе about_CommonParameters.

Примеры

В этих примерах показан эффект различных значений $WarningPreference. Параметр WarningAction переопределяет значение предпочтения.

В этом примере показан эффект значения по умолчанию, continue.

$m = "This action can delete data."
Write-Warning -Message $m

WARNING: This action can delete data.

В этом примере используется параметр WarningAction со значением SilentlyContinue для подавления предупреждения. Сообщение не отображается.

$m = "This action can delete data."
Write-Warning -Message $m -WarningAction SilentlyContinue

В этом примере переменная изменяется $WarningPreference на значение SilentlyContinue . Сообщение не отображается.

$WarningPreference = "SilentlyContinue"
$m = "This action can delete data."
Write-Warning -Message $m

В этом примере параметр WarningAction используется для остановки при создании предупреждения.

$m = "This action can delete data."
Write-Warning -Message $m -WarningAction Stop

WARNING: This action can delete data.
Write-Warning : The running command stopped because the preference variable
  "WarningPreference" or common parameter is set to Stop:
    This action can delete data.
At line:1 char:1
+ Write-Warning -Message $m -WarningAction Stop

В этом примере переменная изменяется $WarningPreference на значение Inquire . Пользователю предлагается подтверждение.

$WarningPreference = "Inquire"
$m = "This action can delete data."
Write-Warning -Message $m

WARNING: This action can delete data.

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):

В этом примере используется параметр WarningAction со значением SilentlyContinue. Команда продолжает выполняться, и сообщение не отображается.

$m = "This action can delete data."
Write-Warning -Message $m -WarningAction SilentlyContinue

В этом примере изменяется $WarningPreference значение stop.

$WarningPreference = "Stop"
$m = "This action can delete data."
Write-Warning -Message $m

WARNING: This action can delete data.
Write-Warning : The running command stopped because the preference variable
  "WarningPreference" or common parameter is set to Stop:
    This action can delete data.
At line:1 char:1
+ Write-Warning -Message $m

В этом примере используется WarningAction со значением Inquire . Пользователю будет предложено при возникновении предупреждения.

$m = "This action can delete data."
Write-Warning -Message $m -WarningAction Inquire

WARNING: This action can delete data.

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):

$WhatIfPreference

Определяет, включена ли функция WhatIf автоматически для каждой команды, поддерживающей ее. Если функция WhatIf включена, командлет сообщает ожидаемый эффект команды, но не выполняет команду.

Допустимы следующие значения.

  • False (0, не включен): (по умолчанию) WhatIf не включен автоматически. Чтобы включить его вручную, используйте параметр WhatIf командлета.
  • True (1, включено): WhatIf автоматически включен для любой команды, поддерживающей ее. Пользователи могут использовать параметр WhatIf со значением False , чтобы отключить его вручную, например -WhatIf:$false.

Примеры

В этих примерах показан эффект различных значений $WhatIfPreference. Они показывают, как использовать параметр WhatIf для переопределения значения предпочтения для определенной команды.

В этом примере показан эффект переменной $WhatIfPreference , заданной по умолчанию, False. Используется Get-ChildItem для проверки наличия файла. Remove-Item удаляет файл. После удаления файла можно проверить удаление с Get-ChildItemпомощью .

Get-ChildItem -Path .\test.txt
Remove-Item -Path ./test.txt

    Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           9/13/2019    10:53             10 test.txt

Get-ChildItem -Path .\test.txt

Get-ChildItem : Cannot find path 'C:\Test\test.txt' because it does not exist.
At line:1 char:1
+ Get-ChildItem -File test.txt

В этом примере показан эффект использования параметра WhatIf при значении $WhatIfPreference False.

Убедитесь, что файл существует.

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           2/28/2019    17:06             12 test2.txt

Используйте параметр WhatIf, чтобы определить результат попытки удаления файла.

Remove-Item -Path .\test2.txt -WhatIf

What if: Performing the operation "Remove File" on target "C:\Test\test2.txt".

Убедитесь, что файл не был удален.

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           2/28/2019    17:06             12 test2.txt

В этом примере показан эффект переменной $WhatIfPreference , заданной значением True. Remove-Item При удалении файла отображается путь к файлу, но файл не удаляется.

Попытка удалить файл. Отображается сообщение о том, что произойдет Remove-Item при выполнении, но файл не удаляется.

$WhatIfPreference = "True"
Remove-Item -Path .\test2.txt

What if: Performing the operation "Remove File" on target "C:\Test\test2.txt".

Используйте Get-ChildItem для проверки того, что файл не был удален.

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           2/28/2019    17:06             12 test2.txt

В этом примере показано, как удалить файл при значении $WhatIfPreference True. Он использует параметр WhatIf со значением $false. Используется Get-ChildItem для проверки удаления файла.

Remove-Item -Path .\test2.txt -WhatIf:$false
Get-ChildItem -Path .\test2.txt

Get-ChildItem : Cannot find path 'C:\Test\test2.txt' because it does not exist.
At line:1 char:1
+ Get-ChildItem -Path .\test2.txt

Ниже приведены примеры командлета Get-Process , который не поддерживает WhatIf и Stop-Process поддерживает WhatIf. Значение $WhatIfPreference переменной — True.

Get-Process не поддерживает WhatIf. При выполнении команды отображается процесс Winword .

Get-Process -Name Winword

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    130   119.84     173.38       8.39   15024   4 WINWORD

Stop-Process поддерживает WhatIf. Процесс Winword не останавливается.

Stop-Process -Name Winword

What if: Performing the operation "Stop-Process" on target "WINWORD (15024)".

Поведение WhatIf можно переопределить Stop-Process с помощью параметра WhatIf со значением$false. Процесс Winword остановлен.

Stop-Process -Name Winword -WhatIf:$false

Чтобы убедиться, что процесс Winword был остановлен, используйте Get-Process.

Get-Process -Name Winword

Get-Process : Cannot find a process with the name "Winword".
  Verify the process name and call the cmdlet again.
At line:1 char:1
+ Get-Process -Name Winword

См. также