Compartilhar via

about_Preference_Variables

  • Artigo

Descrição breve

Variáveis que personalizam o comportamento do PowerShell.

Descrição longa

O PowerShell inclui um conjunto de variáveis que permitem personalizar seu comportamento. Essas variáveis de preferência funcionam como as opções em sistemas baseados em GUI.

As variáveis de preferência afetam o ambiente operacional do PowerShell e todos os comandos são executados no ambiente. Alguns cmdlets têm parâmetros que permitem substituir o comportamento de preferência de um comando específico.

A tabela a seguir lista as variáveis de preferência e seus valores padrão.

Variável Valor Padrão
$ConfirmPreference High
$DebugPreference SilentlyContinue
$ErrorActionPreference Continue
$ErrorView ConciseView
$FormatEnumerationLimit 4
$InformationPreference SilentlyContinue
$LogCommandHealthEvent $false (não registrado)
$LogCommandLifecycleEvent $false (não registrado)
$LogEngineHealthEvent $true (registrado)
$LogEngineLifecycleEvent $true (registrado)
$LogProviderHealthEvent $true (registrado)
$LogProviderLifecycleEvent $true (registrado)
$MaximumHistoryCount 4096
$OFS Caractere de espaço (" ")
$OutputEncoding Objeto UTF8Encoding
$ProgressPreference Continue
$PSDefaultParameterValues @{} (tabela de hash vazia)
$PSEmailServer $null (nenhum)
$PSModuleAutoLoadingPreference All
$PSNativeCommandArgumentPassing Windows no Windows, Standard em não Windows
$PSNativeCommandUseErrorActionPreference $false
$PSSessionApplicationName 'wsman'
$PSSessionConfigurationName 'http://schemas.microsoft.com/powershell/Microsoft.PowerShell'
$PSSessionOption Objeto PSSessionOption
$PSStyle Objeto PSStyle
$Transcript $null (nenhum)
$VerbosePreference SilentlyContinue
$WarningPreference Continue
$WhatIfPreference $false

O PowerShell inclui as seguintes variáveis de ambiente que armazenam as preferências do usuário. Para obter mais informações sobre essas variáveis de ambiente, consulte about_Environment_Variables.

  • $env:PSExecutionPolicyPreference
  • $env:PSModulePath

Observação

As alterações nas variáveis de preferência se aplicam somente no escopo em que são feitas e em quaisquer escopos filho delas. Por exemplo, você pode limitar os efeitos da alteração de uma variável de preferência para uma única função ou script. Para obter mais informações, consulte about_Scopes.

Trabalhando com variáveis de preferência

Este documento descreve cada uma das variáveis de preferência.

Para exibir o valor atual de uma variável de preferência específica, digite o nome da variável. Por exemplo, o comando a seguir exibe o valor da $ConfirmPreference variável.

 $ConfirmPreference

High

Para alterar o valor de uma variável, use uma instrução de atribuição. Por exemplo, a instrução a seguir altera o $ConfirmPreference valor do parâmetro para Médio.

$ConfirmPreference = "Medium"

Os valores definidos são específicos para a sessão atual do PowerShell. Para tornar as variáveis efetivas em todas as sessões do PowerShell, adicione-as ao seu perfil do PowerShell. Para obter mais informações, consulte about_Profiles.

Trabalho remoto

Quando você executa comandos em um computador remoto, os comandos remotos estão sujeitos apenas às preferências definidas no cliente do PowerShell do computador remoto. Por exemplo, quando você executa um comando remoto, o valor da variável do $DebugPreference computador remoto determina como o PowerShell responde às mensagens de depuração.

Para obter mais informações sobre comandos remotos, consulte about_Remote.

$ConfirmPreference

Determina se o PowerShell solicita automaticamente a confirmação antes de executar um cmdlet ou função.

A $ConfirmPreference variável usa um dos ConfirmImpact valores de enumeração: Alto, Médio, Baixo ou Nenhum.

Cmdlets e funções recebem um risco de Alto, Médio ou Baixo. Quando o $ConfirmPreference valor da variável é menor ou igual ao risco atribuído a um cmdlet ou função, o PowerShell solicita automaticamente a confirmação antes de executar o cmdlet ou a função. Para obter mais informações sobre como atribuir um risco a cmdlets ou funções, consulte about_Functions_CmdletBindingAttribute.

Se o valor da variável for None, o $ConfirmPreference PowerShell nunca solicitará automaticamente antes de executar um cmdlet ou função.

Para alterar o comportamento de confirmação de todos os cmdlets e funções na sessão, altere $ConfirmPreference o valor da variável.

Para substituir o parâmetro para um único comando, use o $ConfirmPreference parâmetro Confirm de um cmdlet ou função. Para solicitar confirmação, use -Confirm. Para suprimir a confirmação, use -Confirm:$false.

Valores válidos de $ConfirmPreference:

  • Nenhum: o PowerShell não solicita automaticamente. Para solicitar a confirmação de um comando específico, use o parâmetro Confirm do cmdlet ou da função.
  • Baixo: o PowerShell solicita confirmação antes de executar cmdlets ou funções com risco baixo, médio ou alto.
  • Médio: o PowerShell solicita confirmação antes de executar cmdlets ou funções com um risco médio ou alto.
  • Alto: o PowerShell solicita confirmação antes de executar cmdlets ou funções com alto risco.

Explicação detalhada

O PowerShell pode solicitar automaticamente a confirmação antes de executar uma ação. Por exemplo, quando cmdlet ou função afeta significativamente o sistema para excluir dados ou usar uma quantidade significativa de recursos do sistema.

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"):

A estimativa do risco é um atributo do cmdlet ou da função conhecida como ConfirmImpact. Os usuários não podem alterá-lo.

Cmdlets e funções que podem representar um risco para o sistema têm um parâmetro Confirm que você pode usar para solicitar ou suprimir a confirmação de um único comando.

A maioria dos cmdlets e funções mantém o valor padrão de Médio para ConfirmImpact. $ConfirmPreference é definido como Alto por padrão. Portanto, é raro que os comandos solicitem automaticamente a confirmação quando os usuários não especificam o parâmetro Confirmar . Para estender a solicitação de confirmação automática para mais cmdlets e funções, defina o valor de $ConfirmPreference como Médio ou Baixo.

Exemplos

Este exemplo mostra o efeito do valor padrão da $ConfirmPreference variável, Alto. O valor Alto apenas confirma cmdlets e funções de alto risco. Como a maioria dos cmdlets e funções são de risco médio, eles não são confirmados automaticamente e Remove-Item excluem o arquivo. Adicionar -Confirm ao comando solicita a confirmação do usuário.

$ConfirmPreference

High

Remove-Item -Path C:\temp1.txt

Use -Confirm para solicitar confirmação.

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"):

O exemplo a seguir mostra o efeito de alterar o valor de $ConfirmPreference para Médio. Como a maioria dos cmdlets e funções são de risco médio, eles são confirmados automaticamente. Para suprimir o prompt de confirmação de um único comando, use o parâmetro Confirm com um valor de $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

Determina como o PowerShell responde às mensagens de depuração geradas por um script, cmdlet ou provedor ou por um Write-Debug comando na linha de comando.

A $DebugPreference variável usa um dos ActionPreference valores de enumeração: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend ou Break.

Alguns cmdlets exibem mensagens de depuração, que normalmente são mensagens técnicas projetadas para programadores e profissionais de suporte técnico. Por padrão, as mensagens de depuração não são exibidas, mas você pode exibir mensagens de depuração alterando o valor de $DebugPreference.

Você pode usar o parâmetro comum Debug de um cmdlet para exibir ou ocultar as mensagens de depuração de um comando específico. Para obter mais informações, confira about_CommonParameters.

Os valores válidos são os seguintes:

  • Break – Insira o depurador quando ocorrer um erro ou quando uma exceção for gerada.
  • Parar: Exibe a mensagem de depuração e interrompe a execução. Grava um erro no console.
  • Consultar: Exibe a mensagem de depuração e pergunta se você deseja continuar.
  • Continuar: exibe a mensagem de depuração e continua com a execução.
  • SilentlyContinue: (Padrão) Sem efeito. A mensagem de depuração não é exibida e a execução continua sem interrupção.

Adicionar o parâmetro comum Debug a um comando, quando o comando é configurado para gerar uma mensagem de depuração, altera o $DebugPreference valor da variável para Continue.

Exemplos

Os exemplos a seguir mostram o efeito de alterar os valores de quando um Write-Debug comando é inserido na linha de $DebugPreference comando. A alteração afeta todas as mensagens de depuração, incluindo mensagens geradas por cmdlets e scripts. Os exemplos mostram o parâmetro Debug , que exibe ou oculta as mensagens de depuração relacionadas a um único comando.

Este exemplo mostra o efeito do valor padrão da $DebugPreference variável, SilentlyContinue. Por padrão, a mensagem de depuração do cmdlet não é exibida e o Write-Debug processamento continua. Quando o parâmetro Debug é usado, ele substitui a preferência por um único comando. A mensagem de depuração é exibida.

$DebugPreference

SilentlyContinue

Write-Debug -Message "Hello, World"

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

DEBUG: Hello, World

Este exemplo mostra o efeito de $DebugPreference com o valor Continue . A mensagem de depuração é exibida e o comando continua a processar.

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

DEBUG: Hello, World

Este exemplo usa o parâmetro Debug com um valor de $false para suprimir a mensagem de um único comando. A mensagem de depuração não é exibida.

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

Este exemplo mostra o efeito de $DebugPreference ser definido como o valor Stop . A mensagem de depuração é exibida e o comando é interrompido.

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

Este exemplo usa o parâmetro Debug com um valor de $false para suprimir a mensagem de um único comando. A mensagem de depuração não é exibida e o processamento não é interrompido.

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

Este exemplo mostra o efeito de $DebugPreference ser definido como o valor Inquire . A mensagem de depuração é exibida e o usuário é solicitado a confirmar.

$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"):

Este exemplo usa o parâmetro Debug com um valor de $false para suprimir a mensagem de um único comando. A mensagem de depuração não é exibida e o processamento continua.

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

$ErrorActionPreference

Determina como o PowerShell responde a um erro de não encerramento, um erro que não interrompe o processamento do cmdlet. Por exemplo, na linha de comando ou em um script, cmdlet ou provedor, como os erros gerados pelo Write-Error cmdlet.

A $ErrorActionPreference variável usa um dos ActionPreference valores de enumeração: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend ou Break.

Você pode usar o parâmetro comum ErrorAction de um cmdlet para substituir a preferência por um comando específico.

Os valores válidos são os seguintes:

  • Break – Insira o depurador quando ocorrer um erro ou quando uma exceção for gerada.
  • Continuar: (Padrão) Exibe a mensagem de erro e continua a execução.
  • Ignorar: suprime a mensagem de erro e continua a executar o comando. O valor Ignorar destina-se ao uso por comando, não ao uso como preferência salva. Ignorar não é um valor válido para a $ErrorActionPreference variável.
  • Consultar: Exibe a mensagem de erro e pergunta se você deseja continuar.
  • SilentlyContinue: Sem efeito. A mensagem de erro não é exibida e a execução continua sem interrupção.
  • Parar: Exibe a mensagem de erro e interrompe a execução. Além do erro gerado, o valor Stop gera um objeto ActionPreferenceStopException para o fluxo de erros.
  • Suspender: suspende automaticamente um trabalho de fluxo de trabalho para permitir uma investigação mais aprofundada. Após a investigação, o fluxo de trabalho pode ser retomado. O valor Suspend destina-se ao uso por comando, não ao uso como preferência salva. Suspend não é um valor válido para a $ErrorActionPreference variável.

$ErrorActionPreferencee o parâmetro ErrorAction não afetam como o PowerShell responde a erros de encerramento que interrompem o processamento do cmdlet. Para obter mais informações sobre o parâmetro comum ErrorAction , consulte about_CommonParameters.

Muitos comandos nativos gravam em stderr como um fluxo alternativo para obter informações adicionais. Esse comportamento pode causar confusão ao examinar erros, ou o usuário pode perder as informações de saída adicionais caso $ErrorActionPreference esteja definido como um estado que desativa a saída.

A partir do PowerShell 7.2, os registros de erro redirecionados de comandos nativos, como ao usar operadores de redirecionamento (2>&1), não são gravados na $Error variável e a variável $ErrorActionPreference de preferência não afeta a saída redirecionada.

O PowerShell 7.3 adicionou um recurso experimental que permite controlar como as mensagens gravadas stderr são tratadas.

Para obter mais informações, consulte $PSNativeCommandUseErrorActionPreference.

Exemplos

Esses exemplos mostram o efeito dos diferentes valores da $ErrorActionPreference variável. O parâmetro ErrorAction é usado para substituir o $ErrorActionPreference valor.

Este exemplo mostra o $ErrorActionPreference valor padrão, Continuar. Um erro de não encerramento é gerado. A mensagem é exibida e o processamento continua.

# 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

Este exemplo mostra o $ErrorActionPreference valor padrão, Inquire. Um erro é gerado e um prompt de ação é mostrado.

# 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"):

Este exemplo mostra o $ErrorActionPreference conjunto como SilentlyContinue. A mensagem de erro é suprimida.

# 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

Este exemplo mostra o $ErrorActionPreference conjunto como Stop. Ele também mostra o objeto extra gerado para a $Error variável.

# 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

Determina o formato de exibição das mensagens de erro no PowerShell.

A $ErrorView variável usa um dos ErrorView valores de enumeração: NormalView, CategoryView ou ConciseView.

Os valores válidos são os seguintes:

  • ConciseView: (Padrão) Fornece uma mensagem de erro concisa e uma exibição refatorada para construtores de módulos avançados. A partir do PowerShell 7.2, se o erro for da linha de comando ou de um módulo de script, a saída será uma mensagem de erro de linha única. Caso contrário, você receberá uma mensagem de erro de várias linhas que contém o erro e um ponteiro para o erro mostrando onde ele ocorre nessa linha. Se o terminal for compatível com o Terminal Virtual, os códigos de cores ANSI serão usados para fornecer destaque de cor. A cor de destaque pode ser alterada em $Host.PrivateData.ErrorAccentColor. Use Get-Error o cmdlet para obter uma exibição detalhada abrangente do erro totalmente qualificado, incluindo exceções internas.

    ConciseView foi adicionado no PowerShell 7.

  • NormalView: Uma exibição detalhada projetada para a maioria dos usuários. Consiste em uma descrição do erro e o nome do objeto envolvido no erro.

  • CategoryView: uma exibição sucinta e estruturada projetada para ambientes de produção. A formato funciona da seguinte maneira:

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

Para obter mais informações sobre os campos em CategoryView, consulte Classe ErrorCategoryInfo .

Exemplos

Este exemplo mostra como um erro aparece quando o valor de $ErrorView é o padrão, ConciseView. Get-ChildItem é usado para encontrar um diretório inexistente.

Get-ChildItem -path 'C:\NoRealDirectory'

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

Este exemplo mostra como um erro aparece quando o valor de $ErrorView é o padrão, ConciseView. Script.ps1 é executado e gera um erro de Get-Item instrução.

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

Este exemplo mostra como um erro aparece quando o valor de $ErrorView é alterado para NormalView. Get-ChildItem é usado para localizar um arquivo inexistente.

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

Este exemplo mostra como o mesmo erro aparece quando o valor de $ErrorView é alterado para CategoryView.

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

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

Este exemplo demonstra que o valor de afeta apenas a exibição de $ErrorView erro. Ele não altera a estrutura do objeto de erro armazenado na $Error variável automática. Para obter informações sobre a variável automática, consulte about_automatic_variables$Error.

O comando a seguir usa o objeto ErrorRecord associado ao erro mais recente na matriz de erros, elemento 0, e formata as propriedades do objeto em uma lista.

$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

Determina quantos itens enumerados são incluídos em uma exibição. Essa variável não afeta os objetos subjacentes, apenas a exibição. Quando o valor de $FormatEnumerationLimit é menor que o número de itens enumerados, o PowerShell adiciona reticências (...) para indicar itens não mostrados.

Valores válidos: Inteiros (Int32)

Valor padrão: 4

Exemplos

Este exemplo mostra como usar a $FormatEnumerationLimit variável para melhorar a exibição de itens enumerados.

O comando neste exemplo gera uma tabela que lista todos os serviços em execução no computador em dois grupos: um para serviços em execução e outro para serviços interrompidos . Ele usa um Get-Service comando para obter todos os serviços e, em seguida, envia os resultados por meio do pipeline para o Group-Object cmdlet, que agrupa os resultados pelo status do serviço.

O resultado é uma tabela que lista o status na coluna Nome e os processos na coluna Grupo . Para alterar os rótulos das colunas, use uma tabela de hash, consulte about_Hash_Tables. Para obter mais informações, consulte os exemplos em Format-Table.

Encontre o valor atual de $FormatEnumerationLimit.

$FormatEnumerationLimit

4

Liste todos os serviços agrupados por Status. Há um máximo de quatro serviços listados na coluna Grupo para cada status porque $FormatEnumerationLimit tem um valor de 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...}

Para aumentar o número de itens listados, aumente o valor de $FormatEnumerationLimit para 1000. Use Get-Service e Group-Object exiba os serviços.

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

Use Format-Table com o parâmetro Wrap para exibir a lista de serviços.

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

A $InformationPreference variável permite definir as preferências de fluxo de informações que você deseja exibir aos usuários. Especificamente, mensagens informativas que você adicionou a comandos ou scripts adicionando o cmdlet Write-Information . Se o parâmetro InformationAction for usado, seu valor substituirá o $InformationPreference valor da variável. Write-Information foi introduzido no PowerShell 5.0.

A $InformationPreference variável usa um dos ActionPreference valores de enumeração: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend ou Break.

Os valores válidos são os seguintes:

  • Interromper - Insira o depurador ao gravar no fluxo de informações.
  • Parar: Interrompe um comando ou script em uma ocorrência do Write-Information comando.
  • Consultar: exibe a mensagem informativa especificada em um Write-Information comando e pergunta se deseja continuar.
  • Continuar: Exibe a mensagem informativa e continua em execução.
  • SilentlyContinue: (Padrão) Sem efeito. As mensagens informativas não são exibidas e o script continua sem interrupção.

$Log*Evento

As variáveis de preferência Log*Event determinam quais tipos de eventos são gravados no log de eventos do PowerShell no Visualizador de Eventos. Por padrão, somente os eventos de mecanismo e provedor são registrados. No entanto, você pode usar as variáveis de preferência Log*Event para personalizar seu log, como registrar eventos sobre comandos.

As variáveis de preferência Log*Event são as seguintes:

  • $LogCommandHealthEvent: Registra erros e exceções na inicialização e processamento de comandos. O padrão é $false (não registrado).
  • $LogCommandLifecycleEvent: registra o início e a interrupção de comandos e pipelines de comando e exceções de segurança na descoberta de comandos. O padrão é $false (não registrado).
  • $LogEngineHealthEvent: Registra erros e falhas de sessões. O padrão é $true (logged).
  • $LogEngineLifecycleEvent: Registra a abertura e o fechamento de sessões. O padrão é $true (logged).
  • $LogProviderHealthEvent: registra erros do provedor, como erros de leitura e gravação, erros de pesquisa e erros de invocação. O padrão é $true (logged).
  • $LogProviderLifecycleEvent: Logs adicionando e removendo provedores do PowerShell. O padrão é $true (logged). Para obter informações sobre provedores do PowerShell, consulte about_Providers.

Para habilitar um Log*Event, digite a variável com um valor de $true, por exemplo:

$LogCommandLifeCycleEvent = $true

Para desativar um tipo de evento, digite a variável com um valor de $false, por exemplo:

$LogCommandLifeCycleEvent = $false

Os eventos que você habilita são efetivos apenas para o console atual do PowerShell. Para aplicar a configuração a todos os consoles, salve as configurações de variável em seu perfil do PowerShell. Para obter mais informações, consulte about_Profiles.

$MaximumHistoryCount

Determina quantos comandos são salvos no histórico de comandos da sessão atual.

Valores válidos: 1 - 32768 (Int32)

Padrão: 4096

Para determinar o número de comandos atualmente salvos no histórico de comandos, digite:

(Get-History).Count

Para ver os comandos salvos no histórico da sessão, use o Get-History cmdlet. Para obter mais informações, consulte about_History.

$OFS

O OFS (Separador de Campo de Saída) especifica o caractere que separa os elementos de uma matriz convertida em uma cadeia de caracteres.

Valores válidos: qualquer cadeia de caracteres.

Padrão: Espaço

Por padrão, a $OFS variável não existe e o separador de arquivo de saída é um espaço, mas você pode adicionar essa variável e defini-la como qualquer string. Você pode alterar o valor de $OFS em sua sessão, digitando $OFS="<value>".

Observação

Se você estiver esperando o valor padrão de um espaço (" ") em seu script, módulo ou saída de configuração, tenha cuidado para que o $OFS valor padrão não tenha sido alterado em outro lugar em seu código.

Exemplos

Este exemplo mostra que um espaço é usado para separar os valores quando uma matriz é convertida em uma cadeia de caracteres. Nesse caso, uma matriz de inteiros é armazenada em uma variável e, em seguida, a variável é convertida como uma string.

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

1 2 3 4

Para alterar o separador, adicione a $OFS variável atribuindo um valor a ela. A variável deve ser nomeada $OFS.

$OFS = "+"
[string]$array

1+2+3+4

Para restaurar o comportamento padrão, você pode atribuir um espaço (" ") ao valor ou $OFS excluir a variável. Os comandos a seguir excluem a variável e verificam se o separador é um espaço.

Remove-Variable OFS
[string]$array

1 2 3 4

$OutputEncoding

Determina o método de codificação de caracteres que o PowerShell usa ao canalizar dados para aplicativos nativos.

Observação

Na maioria dos cenários, o valor de $OutputEncoding deve estar alinhado ao valor de [Console]::InputEncoding.

Os valores válidos são os seguintes: Objetos derivados de uma classe Encoding, como ASCIIEncoding, UTF7Encoding, UTF8Encoding, UTF32Copping e UnicodeEncoding.

Padrão: objeto UTF8Encoding .

Exemplos

O primeiro comando localiza o valor de $OutputEncoding. Como o valor é um objeto de codificação, exiba apenas sua propriedade EncodingName .

$OutputEncoding.EncodingName

Os exemplos restantes usam o seguinte script do PowerShell salvo como hexdump.ps1 para ilustrar o comportamento do $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()
}

O exemplo a seguir mostra como o valor café da cadeia de caracteres é codificado em bytes quando canalizado para hexdump.ps1 criado acima. Ele demonstra que o valor da cadeia de caracteres é codificado usando o esquema 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�

O exemplo a seguir mostra como os bytes mudam ao alterar a codificação para UnicodeEncoding.

$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

Determina como o PowerShell responde às atualizações de progresso geradas por um script, cmdlet ou provedor, como as barras de progresso geradas pelo cmdlet Write-Progress . O Write-Progress cmdlet cria barras de progresso que mostram o status de um comando.

A $ProgressPreference variável usa um dos ActionPreference valores de enumeração: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend ou Break.

Os valores válidos são os seguintes:

  • Break – insira o depurador ao gravar no fluxo de progresso.
  • Parar: não exibe a barra de progresso. Em vez disso, ele exibe uma mensagem de erro e interrompe a execução.
  • Consultar: não exibe a barra de progresso. Solicita permissão para continuar. Se você responder com Y ou A, ele exibirá a barra de progresso.
  • Continuar: (Padrão) Exibe a barra de progresso e continua com a execução.
  • SilentlyContinue: executa o comando, mas não exibe a barra de progresso.

$PSDefaultParameterValues

Especifica valores padrão para os parâmetros de cmdlets e funções avançadas. O valor de é uma tabela de $PSDefaultParameterValues hash em que a chave consiste no nome do cmdlet e no nome do parâmetro separados por dois-pontos (:). O valor é um valor padrão personalizado que você especifica.

$PSDefaultParameterValues foi introduzido no PowerShell 3.0.

Para obter mais informações sobre essa variável de preferência, consulte about_Parameters_Default_Values.

$PSEmailServer

Especifica o servidor de email padrão usado para enviar mensagens de email. Essa variável de preferência é usada por cmdlets que enviam emails, como o cmdlet Send-MailMessage .

$PSModuleAutoloadingPreference

Ativa e desativa a importação automática de módulos na sessão. A $PSModuleAutoloadingPreference variável não existe por padrão. O comportamento padrão quando a variável não está definida é o mesmo que $PSModuleAutoloadingPreference = 'All'.

Para importar automaticamente um módulo, obtenha ou use um comando contido no módulo.

A $PSModuleAutoloadingPreference variável usa um dos PSModuleAutoLoadingPreference valores de enumeração:

  • All: Os módulos são importados automaticamente no primeiro uso.
  • ModuleQualified: Os módulos são importados automaticamente somente quando um usuário usa o nome qualificado pelo módulo de um comando no módulo. Por exemplo, se o usuário digitar MyModule\MyCommand, o PowerShell importará o módulo MyModule .
  • None: Desativa a importação automática de módulos. Para importar um módulo, use o Import-Module cmdlet.

Para obter mais informações sobre a importação automática de módulos, consulte about_Modules.

$PSNativeCommandArgumentPassing

O PowerShell 7.3 alterou a maneira como analisa a linha de comando para comandos nativos. A nova $PSNativeCommandArgumentPassing variável de preferência controla esse comportamento.

Cuidado

O novo comportamento é uma alteração significativa em relação ao comportamento anterior. Isso pode interromper scripts e automação que solucionam os diversos problemas que ocorrem ao invocar aplicativos nativos.

A variável $PSNativeCommandArgumentPassing automática permite selecionar o comportamento em tempo de execução. Os valores válidos são Legacy, Standard e Windows. Legacy é o comportamento histórico.

A $PSNativeCommandArgumentPassing variável é definida por padrão, mas o valor é específico da plataforma.

  • No Windows, a preferência é definida como Windows.
  • Em plataformas não Windows, a preferência é definida como Standard.
  • Se você tiver removido a variável, o $PSNativeCommandArgumentPassing PowerShell usará o Standard comportamento.

O comportamento de Windows e Standard o modo são os mesmos, exceto que, no Windows modo, o PowerShell usa o Legacy comportamento de passagem de argumento quando você executa os arquivos a seguir.

  • cmd.exe
  • cscript.exe
  • find.exe
  • sqlcmd.exe
  • wscript.exe
  • Arquivos que terminam com:
    • .bat
    • .cmd
    • .js
    • .vbs
    • .wsf

Se o $PSNativeCommandArgumentPassing estiver definido como Legacy ou Standard, o analisador não verificará esses arquivos. Para obter exemplos do novo comportamento, consulte about_Parsing.

O PowerShell 7.3 também adicionou a capacidade de rastrear a associação de parâmetros para comandos nativos. Para obter mais informações, confira Trace-Command.

$PSNativeCommandUseErrorActionPreference

Quando $PSNativeCommandUseErrorActionPreference é $true, comandos nativos com códigos de saída diferentes de zero emitem erros de acordo $ErrorActionPreferencecom .

Alguns comandos nativos, como robocopy , usam códigos de saída diferentes de zero para representar informações que não sejam erros. Nesses casos, você pode desativar temporariamente o comportamento e impedir que códigos de saída diferentes de zero emitam erros.

& {
    # 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"
    }
}

Neste exemplo, a $PSNativeCommandUseErrorActionPreference variável é alterada dentro de um scriptblock. A alteração é local para o scriptblock. Quando o scriptblock é encerrado, a variável é revertida para seu valor anterior.

$PSSessionApplicationName

Especifica o nome do aplicativo padrão para um comando remoto que usa a tecnologia Web Services for Management (WS-Management). Para obter mais informações, consulte Sobre o Gerenciamento Remoto do Windows.

O nome padrão do aplicativo do sistema é WSMAN, mas você pode usar essa variável de preferência para alterar o padrão.

O nome do aplicativo é o último nó em um URI de conexão. Por exemplo, o nome do aplicativo no URI de exemplo a seguir é WSMAN.

http://Server01:8080/WSMAN

O nome do aplicativo padrão é usado quando o comando remoto não especifica um URI de conexão ou um nome de aplicativo.

O serviço WinRM usa o nome do aplicativo para selecionar um ouvinte para atender à solicitação de conexão. O valor do parâmetro deve corresponder ao valor da propriedade URLPrefix de um ouvinte no computador remoto.

Para substituir o padrão do sistema e o valor dessa variável e selecionar um nome de aplicativo diferente para uma sessão específica, use os parâmetros ConnectionURI ou ApplicationName dos cmdlets New-PSSession, Enter-PSSession ou Invoke-Command .

A $PSSessionApplicationName variável de preferência é definida no computador local, mas especifica um ouvinte no computador remoto. Se o nome do aplicativo especificado não existir no computador remoto, o comando para estabelecer a sessão falhará.

$PSSessionConfigurationName

Especifica a configuração de sessão padrão usada para criar novas sessões na sessão atual.

Essa variável de preferência é definida no computador local, mas especifica uma configuração de sessão localizada no computador remoto.

O valor da $PSSessionConfigurationName variável é um URI de recurso totalmente qualificado.

O valor http://schemas.microsoft.com/PowerShell/microsoft.PowerShell padrão indica a configuração de sessão do Microsoft.PowerShell no computador remoto.

Se você especificar apenas um nome de configuração, o seguinte URI de esquema será anexado:

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

Você pode substituir o padrão e selecionar uma configuração de sessão diferente para uma sessão específica usando o parâmetro ConfigurationName dos New-PSSessioncmdlets , Enter-PSSessionou Invoke-Command .

Você pode alterar o valor dessa variável a qualquer momento. Ao fazer isso, lembre-se de que a configuração de sessão selecionada deve existir no computador remoto. Caso contrário, o comando para criar uma sessão que usa a configuração da sessão falhará.

Essa variável de preferência não determina quais configurações de sessão local são usadas quando os usuários remotos criam uma sessão que se conecta a este computador. No entanto, você pode usar as permissões para as configurações de sessão local para determinar quais usuários podem usá-las.

$PSSessionOption

Estabelece os valores padrão para opções avançadas do usuário em uma sessão remota. Essas preferências de opção substituem os valores padrão do sistema para opções de sessão.

A $PSSessionOption variável contém um objeto PSSessionOption . Para obter mais informações, consulte System.Management.Automation.Remoting.PSSessionOption. Cada propriedade do objeto representa uma opção de sessão. Por exemplo, a propriedade NoCompression transforma a compactação de dados durante a sessão.

Por padrão, a $PSSessionOption variável contém um objeto PSSessionOption com os valores padrão para todas as opções, conforme mostrado abaixo.

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

Para obter descrições dessas opções e mais informações, consulte New-PSSessionOption. Para obter mais informações sobre comandos e sessões remotas, consulte about_Remote e about_PSSessions.

Para alterar o valor da variável de preferência, use o New-PSSessionOption cmdlet para criar um objeto PSSessionOption com os valores de $PSSessionOption opção de sua preferência. Salve a saída em uma variável chamada $PSSessionOption.

$PSSessionOption = New-PSSessionOption -NoCompression

Para usar a $PSSessionOption variável de preferência em cada sessão do PowerShell, adicione um New-PSSessionOption comando que crie a $PSSessionOption variável ao seu perfil do PowerShell. Para obter mais informações, consulte about_Profiles.

Você pode definir opções personalizadas para uma sessão remota específica. As opções definidas têm precedência sobre os padrões do sistema e o valor da variável de $PSSessionOption preferência.

Para definir opções de sessão personalizadas, use o New-PSSessionOption cmdlet para criar um objeto PSSessionOption . Em seguida, use o objeto PSSessionOption como o valor do parâmetro SessionOption em cmdlets que criam uma sessão, como New-PSSession, Enter-PSSessione Invoke-Command.

$PSStyle

A partir do PowerShell 7.2, agora você pode acessar a $PSStyle variável automática para exibir e alterar a renderização da saída da cadeia de caracteres ANSI. $PSStyle é uma instância da classe PSStyle . Os membros dessa classe definem strings contendo sequências de escape ANSI que controlam a renderização de texto no terminal.

Os membros de base retornam cadeias de caracteres de sequências de escape ANSI mapeadas para seus nomes. Os valores são configuráveis para permitir a personalização. Os nomes de propriedade facilitam a criação de cadeias de caracteres decoradas usando o preenchimento de tabulação. Por exemplo:

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

Os membros Background e Foreground também têm um FromRgb() método para especificar a cor de 24 bits.

Para mais informações sobre $PSStyle, confira about_ANSI_Terminals.

$Transcript

Usado por Start-Transcript para especificar o nome e o local do arquivo de transcrição. Se você não especificar um valor para o parâmetro Path , Start-Transcript usará o caminho no valor da $Transcript variável global. Se você não criou essa variável, Start-Transcript armazena as transcrições no seguinte local usando o nome padrão:

  • No Windows: $HOME\Documents
  • No Linux ou macOS: $HOME

O nome de arquivo padrão é: PowerShell_transcript.<computername>.<random>.<timestamp>.txt.

$VerbosePreference

Determina como o PowerShell responde a mensagens detalhadas geradas por um script, cmdlet ou provedor, como as mensagens geradas pelo cmdlet Write-Verbose . Mensagens detalhadas descrevem as ações executadas para executar um comando.

Por padrão, as mensagens detalhadas não são exibidas, mas você pode alterar esse comportamento alterando o valor de $VerbosePreference.

A $VerbosePreference variável usa um dos ActionPreference valores de enumeração: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend ou Break.

Os valores válidos são os seguintes:

  • Break – insira o depurador ao gravar no fluxo detalhado.
  • Parar: Exibe a mensagem detalhada e uma mensagem de erro e, em seguida, interrompe a execução.
  • Consultar: Exibe a mensagem detalhada e, em seguida, exibe um prompt que pergunta se você deseja continuar.
  • Continuar: Exibe a mensagem detalhada e continua com a execução.
  • SilentlyContinue: (Padrão) não exibe a mensagem detalhada. Continua em execução.

Você pode usar o parâmetro comum detalhado de um cmdlet para exibir ou ocultar as mensagens detalhadas de um comando específico. Para obter mais informações, confira about_CommonParameters.

Exemplos

Esses exemplos mostram o efeito dos diferentes valores de $VerbosePreference e do parâmetro Verbose para substituir o valor de preferência.

Este exemplo mostra o efeito do valor SilentlyContinue , que é o padrão. O comando usa o parâmetro Message , mas não grava uma mensagem no console do PowerShell.

Write-Verbose -Message "Verbose message test."

Quando o parâmetro Verbose é usado, a mensagem é gravada.

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

VERBOSE: Verbose message test.

Este exemplo mostra o efeito do valor Continue . A $VerbosePreference variável é definida como Continuar e a mensagem é exibida.

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

VERBOSE: Verbose message test.

Este exemplo usa o parâmetro Verbose com um valor que substitui o valor Continue$false. A mensagem não é exibida.

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

Este exemplo mostra o efeito do valor Stop . A $VerbosePreference variável é definida como Stop e a mensagem é exibida. O comando é interrompido.

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

Este exemplo usa o parâmetro Verbose com um valor que substitui o valor Stop$false. A mensagem não é exibida.

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

Este exemplo mostra o efeito do valor Inquire . A $VerbosePreference variável é definida como Inquire. A mensagem é exibida e o usuário é solicitado a confirmar.

$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"):

Este exemplo usa o parâmetro Verbose com um valor de $false que substitui o valor Inquire . O usuário não é solicitado e a mensagem não é exibida.

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

$WarningPreference

Determina como o PowerShell responde a mensagens de aviso geradas por um script, cmdlet ou provedor, como as mensagens geradas pelo cmdlet Write-Warning .

Por padrão, as mensagens de aviso são exibidas e a execução continua, mas você pode alterar esse comportamento alterando o valor de $WarningPreference.

A $WarningPreference variável usa um dos ActionPreference valores de enumeração: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend ou Break.

Os valores válidos são os seguintes:

  • Break - Insira o depurador quando uma mensagem de aviso for gravada.
  • Parar: Exibe a mensagem de aviso e uma mensagem de erro e, em seguida, interrompe a execução.
  • Consultar: Exibe a mensagem de aviso e solicita permissão para continuar.
  • Continuar: (Padrão) Exibe a mensagem de aviso e continua a execução.
  • SilentlyContinue: não exibe a mensagem de aviso. Continua em execução.

Você pode usar o parâmetro comum WarningAction de um cmdlet para determinar como o PowerShell responde a avisos de um comando específico. Para obter mais informações, confira about_CommonParameters.

Exemplos

Esses exemplos mostram o efeito dos diferentes valores de $WarningPreference. O parâmetro WarningAction substitui o valor de preferência.

Este exemplo mostra o efeito do valor padrão, Continuar.

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

WARNING: This action can delete data.

Este exemplo usa o parâmetro WarningAction com o valor SilentlyContinue para suprimir o aviso. A mensagem não é exibida.

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

Este exemplo altera a $WarningPreference variável para o valor SilentlyContinue . A mensagem não é exibida.

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

Este exemplo usa o parâmetro WarningAction para parar quando um aviso é gerado.

$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

Este exemplo altera a $WarningPreference variável para o valor Inquire . O usuário é solicitado a confirmar.

$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"):

Este exemplo usa o parâmetro WarningAction com o valor SilentlyContinue. O comando continua a ser executado e nenhuma mensagem é exibida.

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

Este exemplo altera o $WarningPreference valor para 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

Este exemplo usa o WarningAction com o valor Inquire . O usuário é avisado quando ocorre um aviso.

$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

Determina se o WhatIf é habilitado automaticamente para cada comando que dá suporte a ele. Quando WhatIf está habilitado, o cmdlet relata o efeito esperado do comando, mas não executa o comando.

Os valores válidos são os seguintes:

  • Falso (0, não habilitado): (Padrão) WhatIf não é habilitado automaticamente. Para habilitá-lo manualmente, use o parâmetro WhatIf do cmdlet.
  • True (1, habilitado): WhatIf é habilitado automaticamente em qualquer comando que dê suporte a ele. Os usuários podem usar o parâmetro WhatIf com um valor de False para desativá-lo manualmente, como -WhatIf:$false.

Exemplos

Esses exemplos mostram o efeito dos diferentes valores de $WhatIfPreference. Eles mostram como usar o parâmetro WhatIf para substituir o valor de preferência de um comando específico.

Este exemplo mostra o efeito da $WhatIfPreference variável definida como o valor padrão, False. Use Get-ChildItem para verificar se o arquivo existe. Remove-Item exclui o arquivo. Depois que o arquivo for excluído, você poderá verificar a exclusão com 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

Este exemplo mostra o efeito do uso do parâmetro WhatIf quando o valor de $WhatIfPreference é False.

Verifique se o arquivo existe.

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

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

Use o parâmetro WhatIf para determinar o resultado da tentativa de excluir o arquivo.

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

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

Verifique se o arquivo não foi excluído.

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

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

Este exemplo mostra o efeito da $WhatIfPreference variável definida como o valor True. Quando você usa Remove-Item para excluir um arquivo, o caminho do arquivo é exibido, mas o arquivo não é excluído.

Tente excluir um arquivo. Uma mensagem é exibida sobre o que aconteceria se Remove-Item fosse executado, mas o arquivo não foi excluído.

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

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

Use Get-ChildItem para verificar se o arquivo não foi excluído.

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

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

Este exemplo mostra como excluir um arquivo quando o valor de $WhatIfPreference é True. Ele usa o parâmetro WhatIf com um valor de $false. Use Get-ChildItem para verificar se o arquivo foi excluído.

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

Veja a Get-Process seguir exemplos do cmdlet que não dá suporte a WhatIf e Stop-Process que dá suporte a WhatIf. O $WhatIfPreference valor da variável é True.

Get-Process não suporta WhatIf. Quando o comando é executado, ele exibe o processo 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-Processsuporta WhatIf. O processo Winword não é interrompido.

Stop-Process -Name Winword

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

Você pode substituir o Stop-Process comportamento WhatIf usando o parâmetro WhatIf com um valor de $false. O processo Winword é interrompido.

Stop-Process -Name Winword -WhatIf:$false

Para verificar se o processo Winword foi interrompido, use 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

Confira também