TÓPICO
about_CommonParameters
DESCRIÇÃO RESUMIDA
Descreve os parâmetros que podem ser usados com qualquer cmdlet.
DESCRIÇÃO LONGA
Os parâmetros comuns são um conjunto de parâmetros de cmdlet que
você pode usar com qualquer cmdlet. Eles são implementados pelo
Windows PowerShell, não pelo desenvolvedor do cmdlet, e ficam
automaticamente disponíveis para qualquer cmdlet.
Você pode usar os parâmetros comuns com qualquer cmdlet, mas
talvez eles não tenham efeitos sobre todos os cmdlets. Por
exemplo, se um cmdlet não gerar uma saída detalhada, usar o
parâmetro comum Verbose não terá qualquer efeito.
Vários parâmetros comuns substituem padrões ou preferências do
sistema que você define usando as variáveis de preferência do Windows
PowerShell. Ao contrário das variáveis de preferência, os parâmetros
comuns afetam apenas os comandos nos quais são usados.
Além dos parâmetros comuns, muitos cmdlets oferecem os parâmetros
de redução de risco WhatIf e Confirm. Os cmdlets que envolvem
risco para o sistema ou para os dados de usuários normalmente
oferecem esses parâmetros.
Os parâmetros comuns são:
-Verbose
-Debug
-WarningAction
-WarningVariable
-ErrorAction
-ErrorVariable
-OutVariable
-OutBuffer
Os parâmetros de redução de risco são:
-WhatIf
-Confirm
Para obter mais informações sobre variáveis de preferência, digite:
help about_preference_variables
Descrições de parâmetros comuns
-Verbose[:{$true | $false}]
Exibe informações detalhadas sobre a operação executada pelo
comando. Essas informações são semelhantes às encontradas em
um log de rastreamento ou de transação. Esse parâmetro só funciona
quando o comando gera uma mensagem detalhada. Por exemplo, esse
parâmetro funciona quando um comando contém o cmdlet Write-Verbose.
O parâmetro Verbose substitui o valor da variável
$VerbosePreference para o comando atual. Como o valor padrão
da variável $VerbosePreference é SilentlyContinue, as mensagens
detalhadas não são exibidas por padrão.
Valores válidos:
$true (-Verbose:$true) tem o mesmo efeito que -Verbose.
$false (-Verbose:$false) suprime a exibição da mensagem
detalhada. Use esse parâmetro quando o valor de $
VerbosePreference não for SilentlyContinue (o padrão).
-Debug[:{$true | $false}]
Exibe detalhes no nível do programador sobre a operação
executada pelo comando. Esse parâmetro só funciona quando o
comando gera uma mensagem de depuração. Por exemplo, esse
parâmetro funciona quando um comando contém o cmdlet Write-Debug.
O parâmetro Debug substitui o valor da variável
$DebugPreference para o comando atual. Como o valor padrão da
variável $DebugPreference é SilentlyContinue, as mensagens de
depuração não são exibidas por padrão.
Valores válidos:
$true (-Debug:$true). Tem o mesmo efeito que -Debug.
$false (-Debug:$false). Suprime a exibição de mensagens
de depuração quando o valor de $DebugPreference não é
SilentlyContinue (o padrão).
-WarningAction[:{SilentlyContinue | Continue | Inquire | Stop}]
Determina como o cmdlet responde a um aviso do comando.
"Continue" é o valor padrão. Esse parâmetro só funciona
quando o comando gera uma mensagem de aviso. Por exemplo,
esse parâmetro funciona quando um comando contém o cmdlet
Write-Warning.
O parâmetro WarningAction substitui o valor da variável
$WarningPreference para o comando atual. Como o valor padrão da variável
$WarningPreference é Continue, são exibidos avisos e a execução
continua a menos que você use o parâmetro WarningAction.
Valores válidos:
SilentlyContinue. Suprime a mensagem de aviso e continua
executando o comando.
Continue. Exibe a mensagem de aviso e continua executando
o comando. "Continue" é o valor padrão.
Inquire. Exibe a mensagem de aviso e solicita sua
confirmação antes de continuar a execução. Esse valor
raramente é usado.
Stop. Exibe a mensagem de aviso e para de executar o comando.
-WarningVariable [+]<nome-da-variável>
Armazena avisos sobre o comando na variável especificada.
Para acrescentar os avisos ao conteúdo da variável, em vez de
substituir avisos que talvez já estejam armazenados, digite
um sinal de adição (+) antes do nome da variável.
Por exemplo, o comando a seguir cria a variável $a e armazena
qualquer aviso nela:
get-process -id 6 -WarningVariable a
O comando a seguir adiciona avisos à variável $a:
get-process -id 2 -WarningVariable +a
O comando a seguir exibe o conteúdo de $a:
$a
Você pode usar esse parâmetro para criar uma variável que
contém apenas avisos de comandos específicos. Você pode usar
a notação de matriz, como $a[0] ou $warning[1,2] para fazer
referência a avisos específicos armazenados na variável.
-ErrorAction[:{SilentlyContinue | Continue | Inquire | Stop)]
Determina como o cmdlet responde a um erro de não-encerramento do
comando. Esse parâmetro só funciona quando o comando gera uma mensagem
de depuração. Por exemplo, esse parâmetro funciona quando um comando
contém o cmdlet Write-Error.
O parâmetro ErrorAction substitui o valor da variável
$ErrorActionPreference para o comando atual. Como o valor padrão da
variável $ErrorActionPreference é Continue, são exibidas mensagens de
erro e a execução continua a menos que você use o parâmetro ErrorAction.
O parâmetro ErrorAction não tem efeito sobre erros de
encerramento (como dados perdidos, parâmetros inválidos ou
permissões insuficientes) que impedem a execução bem-sucedida
de um comando.
Valores válidos:
SilentlyContinue. Suprime a mensagem de erro e continua
executando o comando.
Continue. Exibe a mensagem de erro e continua executando
o comando. "Continue" é o valor padrão.
Inquire. Exibe a mensagem de erro e solicita sua
confirmação antes de continuar a execução. Esse valor
raramente é usado.
Stop. Exibe a mensagem de erro e para de executar o comando.
-ErrorVariable [+]<nome-da-variável>
Armazena mensagens de erro sobre o comando na variável
especificada e na variável automática $Error. Para obter mais
informações, digite o seguinte comando:
get-help about_automatic_variables
Por padrão, novas mensagens de erro substituem mensagens de
erro que já estão armazenadas na variável. Para acrescentar a
mensagem de erro ao conteúdo da variável, digite um sinal de
adição (+) antes do nome da variável.
Por exemplo, o comando a seguir cria a variável $a e armazena
qualquer erro nela:
get-process -id 6 -ErrorVariable a
O comando a seguir adiciona mensagens de erro à variável $a:
get-process -id 2 -ErrorVariable +a
O comando a seguir exibe o conteúdo de $a:
$a
Você pode usar esse parâmetro para criar uma variável que
contém apenas mensagens de erro de comandos específicos. A
variável automática $Error contém mensagens de erro de todos
os comandos na sessão.Você pode usar a notação de matriz,
como $a[0] ou $error[1,2] para fazer referência a erros
específicos armazenados nas variáveis.
-OutVariable [+]<nome-da-variável>
Armazena objetos de saída do comando na variável especificada
e a exibe na linha de comando.
Para adicionar a saída à variável, em vez de substituir
qualquer saída que já possa estar armazenada nela, digite um
sinal de adição (+) antes do nome da variável.
Por exemplo, o comando a seguir cria a variável $out e
armazena o objeto de processo nela:
get-process powershell -OutVariable out
O comando a seguir adiciona o objeto de processo à variável $out:
get-process iexplore -OutVariable +out
O comando a seguir exibe o conteúdo da variável $out.
$out
-OutBuffer <Int32>
Determina o número de objetos a serem acumulados em um buffer
antes de enviar qualquer objeto pelo pipeline. Se você omitir esse
parâmetro, os objetos serão enviados depois de gerados.
Esse parâmetro de gerenciamento de recursos foi criado para
usuários avançados.
Quando você usa esse parâmetro, o Windows PowerShell só chama
o próximo cmdlet no pipeline quando o número de objetos
gerados é igual a OutBuffer + 1. Depois disso, ele envia todos os
objetos assim que são gerados.
Descrições de parâmetros de gerenciamento de riscos
-WhatIf[:{$true | $false}]
Exibe uma mensagem que descreve o efeito do comando, em vez
de executá-lo.
O parâmetro WhatIf substitui o valor da variável
$WhatIfPreference para o comando atual. Como o valor padrão
da variável $WhatIfPreference é 0 (desabilitado), o
comportamento de WhatIf não é executado sem o parâmetro
WhatIf. Para obter mais informações, digite o seguinte comando:
get-help about_preference_variables
Valores válidos:
$true (-WhatIf:$true). Tem o mesmo efeito que -WhatIf.
$false (-WhatIf:$false). Suprime o comportamento automático de
WhatIf que ocorre quando o valor da variável $WhatIfPreference é 1.
Por exemplo, o comando a seguir usa o parâmetro WhatIf em um
comando Remove-Item:
PS> remove-item date.csv -whatif
Em vez de remover o item, o Windows PowerShell lista as
operações que executaria e os itens que seriam afetados. Esse
comando gera a seguinte saída:
Whatif: Realizando a operação "Remover Arquivo" no
Destino "C:\ps-test\date.csv".
-Confirm[:{$true | $false}]
Solicita confirmação antes da execução do comando.
O parâmetro Confirm substitui o valor da variável
$ConfirmPreference para o comando atual. O valor padrão é
High. Para obter mais informações, digite o seguinte comando:
get-help about_preference_variables
Valores válidos:
$true (-WhatIf:$true). Tem o mesmo efeito que -Confirm.
$false(-Confirm:$false). Suprime a confirmação automática
que ocorre quando o valor da variável $ConfirmPreference
é menor ou igual ao risco estimado do cmdlet.
Por exemplo, o comando a seguir usa o parâmetro Confirm com
um comando Remove-Item. Antes de remover o item, o Windows
PowerShell lista as operações que executaria e os itens que seriam
afetados e solicita aprovação.
PS C:\ps-test> remove-item tmp*.txt -confirm
Esse comando gera a seguinte saída:
Confirm
Tem certeza de que deseja executar esta ação?
Realizando a operação "Remover Arquivo" no Destino " C:\ps-
test\tmp1.txt [S] Sim [A] Sim para Todos [N] Não [T] Não para Todos
[U] Suspender [?] Ajuda (o padrão é "S"):
CONSULTE TAMBÉM
about_Preference_Variables
Write-Debug
Write-Warning
Write-Error
Write-Verbose