about_CommonParameters
Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
Insira a introdução aqui.
TÓPICO
about_CommonParameters
DESCRIÇÃO BREVE
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 por Windows PowerShell®, não pelo desenvolvedor de cmdlet e eles ficam automaticamente disponíveis para qualquer cmdlet.
Você pode usar os parâmetros comuns com qualquer cmdlet, mas eles talvez não tenham efeito em todos os cmdlets. Por exemplo, se um cmdlet não gera nenhuma saída detalhada, usar o parâmetro comum Verbose não terá efeito.
Os parâmetros comuns também estão disponíveis em funções avançadas que usam o atributo CmdletBinding ou o atributo Parameter, e em todos os fluxos de trabalho.
Vários parâmetros comuns substituem padrões do sistema ou preferências que podem ser definidas usando as variáveis de preferências do Windows PowerShell. Ao contrário das variáveis de preferência, os parâmetros comuns afetam somente os comandos nos quais eles 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 ao sistema ou aos dados de usuário geralmente oferecem esses parâmetros.
A lista a seguir exibe os parâmetros comuns. Seus aliases são listados entre parênteses.
-Debug (db)
-ErrorAction (ea)
-ErrorVariable (ev)
-OutVariable (ov)
-OutBuffer (ob)
-PipelineVariable (pv)
-Verbose (vb)
-WarningAction (wa)
-WarningVariable (wv
Os parâmetros de redução de risco são:
-WhatIf (wi)
-Confirm (cf)
Para obter mais informações sobre variáveis de preferências, digite:
help about_Preference_Variables
DESCRIÇÕES DE PARÂMETRO COMUM
-DEBUG[:{$TRUE | $FALSE}]
Alias: db
Exibe detalhes 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, definindo o valor de $DebugPreference como Inquire. 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). Has the same effect as -Debug.
$false (-Debug:$false). Suppresses the display of debugging
messages when the value of the $DebugPreference is not
SilentlyContinue (the default).
-ERRORACTION[:{CONTINUE | IGNORE | INQUIRE | SILENTLYCONTINUE | STOP |SUSPEND }]
Alias: ea
Determina como o cmdlet responde a um erro de não finalização do comando. Esse parâmetro só funciona quando o comando gera um erro de não finalização, como aqueles do 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, as mensagens de erro são exibidas e a execução continua a menos que você use o parâmetro ErrorAction.
O parâmetro ErrorAction não tem nenhum efeito no encerramento de erros (como ausência de dados, parâmetros que não são válidos ou permissões insuficientes) que impedem que um comando seja concluído com êxito.
Valores válidos:
Continue. Exibe a mensagem de erro e continua executando o comando. "Continue" é o valor padrão.
Ignore. Suprime a mensagem de erro e continua executando o comando. Diferentemente de SilentlyContinue, Ignore não adiciona a mensagem de erro à variável automática $Error. O valor Ignore é apresentado no Windows PowerShell 3.0.
Inquire. Exibe a mensagem de erro e solicita sua confirmação antes de continuar a execução. Esse valor é raramente usado.
SilentlyContinue. Suprime a mensagem de erro e continua executando o comando.
Stop. Exibe a mensagem de erro e interrompe a execução do comando.
Suspend. Esse valor só está disponível nos fluxos de trabalho do Windows PowerShell. Quando um fluxo de trabalho é executado no encerramento de um erro, essa preferência de ação automaticamente suspende o trabalho para permitir uma investigação mais detalhada. Após a investigação, o fluxo de trabalho poderá ser retomado.
-ERRORVARIABLE [+]<VARIABLE-NAME>
Alias: ev
Armazena mensagens de erro sobre o comando na variável especificada e na variável $Error automática. 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 anexar 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 uma variável $a e, em seguida, armazena os erros nela:
Get-Process -Id 6 -ErrorVariable a
O comando a seguir adiciona qualquer mensagem de erro a uma 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 as 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, por exemplo $a[0] ou $error[1,2], para se referir a erros específicos armazenados nas variáveis.
-OUTBUFFER <INT32>
Alias: ob
Determina o número de objetos para acumular em um buffer antes de todos os objetos serem enviados por meio do pipeline. Se você omitir esse parâmetro, os objetos são enviados do modo que são gerados.
Esse parâmetro de gerenciamento de recursos destina-se a usuários avançados. Quando você usa esse parâmetro, o Windows PowerShell não chama o próximo cmdlet no pipeline até que o número de objetos gerados seja igual a OutBuffer + 1. Depois disso, ele envia todos os objetos do modo que são gerados.
-OUTVARIABLE [+]<VARIABLE-NAME>
Alias: ov
Armazena objetos de saída do comando na variável especificada e o exibe na linha de comando.
Para adicionar a saída à variável, em vez de substituir qualquer saída que já pode ter sido armazenada lá, digite um sinal de adição (+) antes do nome da variável.
Por exemplo, o comando a seguir cria uma variável $out e, em seguida, armazena o objeto de processo nela:
Get-Process PowerShell -OutVariable out
O comando a seguir adiciona o objeto de processo na variável $out:
Get-Process iexplore -OutVariable +out
O comando a seguir exibe o conteúdo da variável $out:
$out
-PIPELINEVARIABLE <STRING>
Alias: pv
PipelineVariable armazena o valor do elemento de pipeline atual como uma variável para qualquer comando nomeado conforme ela flui pelo pipeline.
Os valores válidos são cadeias de caracteres, da mesma maneira que qualquer nome de variável.
Este é um exemplo de como funciona o PipelineVariable. Neste exemplo, o parâmetro PipelineVariable é adicionado a um comando Foreach-Object para armazenar os resultados do comando em variáveis. Um intervalo de números, de 1 a 10, é canalizado para o primeiro comando Foreach-Object, cujos resultados são armazenados em uma variável chamada Left.
Os resultados do primeiro comando Foreach-Object são canalizados em um segundo comando Foreach-Object, que filtra os objetos retornados pelo primeiro comando Foreach-Object. Os resultados do segundo comando são armazenados em uma variável chamada Right.
No terceiro comando Foreach-Object, os resultados dos dois primeiros comandos Foreach-Object canalizados, representados pelas variáveis Left e Right, são processados usando um operador de multiplicação. O comando instrui que os objetos armazenados nas variáveis Left e Right sejam multiplicados e especifica que os resultados devem ser exibidos como "membro de intervalo Left * membro de intervalo Right = produto".
1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
>> Foreach-Object -PV Right -Process { 1..10 } |
>> Foreach-Object -Process { "$Left * $Right = " + ($Left * $Right) }
>>
1 * 1 = 1
1 * 2 = 2
1 * 3 = 3
1 * 4 = 4
1 * 5 = 5
-VERBOSE[:{$TRUE | $FALSE}]
Alias: vb
Exibe informações detalhadas sobre a operação executada pelo comando. Essas informações se parecem com as informações em um rastreamento ou em um log de transações. 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) has the same effect as -Verbose.
$false (-Verbose:$false) suppresses the display of verbose
messages. Use this parameter when the value of $VerbosePreference
is not SilentlyContinue (the default).
-WARNINGACTION[:{CONTINUE | INQUIRE | SILENTLYCONTINUE | STOP}]
Alias: wa
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, os avisos são exibidos e a execução continua a menos que você use o parâmetro WarningAction.
Valores válidos:
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.
SilentlyContinue. Suprime a mensagem de aviso e continua executando o comando.
Stop. Exibe a mensagem de aviso e interrompe a execução do comando.
OBSERVAÇÃO: O parâmetro WarningAction não substitui o valor da variável de preferência $WarningAction quando o parâmetro é usado em um comando para executar um script ou uma função.
-WARNINGVARIABLE [+]<VARIABLE-NAME>
Alias: wv
Armazena avisos sobre o comando na variável especificada.
Todos os avisos gerados são salvos na variável, mesmo se os avisos não forem exibidos ao usuário.
Para anexar os avisos ao conteúdo da variável, em vez de substituir qualquer aviso que já pode ter sido armazenado lá, digite um sinal de adição (+) antes do nome da variável.
Por exemplo, o comando a seguir cria uma variável $a e, em seguida, armazena os avisos nela:
Get-Process -Id 6 -WarningVariable a
O comando a seguir adiciona qualquer aviso a uma 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, por exemplo $a[0] ou $warning[1,2], para se referir a avisos específicos armazenados nas variáveis.
OBSERVAÇÃO: O parâmetro WarningVariable não captura avisos de chamadas aninhadas em funções ou scripts.
DESCRIÇÕES DE PARÂMETROS DE GERENCIAMENTO DE RISCO
-WHATIF[:{$TRUE | $FALSE}]
Alias: wi
Exibe uma mensagem que descreve o efeito do comando, em vez de executar o comando.
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 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). Has the same effect as -WhatIf.
$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
that results when the value of the $WhatIfPreference variable
is 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 deseja executar e os itens que seriam afetados. Esse comando gera a seguinte saída:
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
-CONFIRM[:{$TRUE | $FALSE}]
Alias: cf
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 (-Confirm:$true). Has the same effect as -Confirm.
$false(-Confirm:$false). Suppresses automatic confirmation,
which occurs when the value of $ConfirmPreference is less than
or equal to the estimated risk of the cmdlet.
Por exemplo, o comando a seguir usa o parâmetro Confirm em um comando Remove-Item. Antes de remover o item, o Windows PowerShell lista as operações que deseja executar 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
Are you sure you want to perform this action?
Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend
[?] Help (default is "Y"):
As opções de resposta de confirmação são as seguintes:
Yes (Y) Perform the action.
Yes to All (A) Perform all actions and suppress subsequent
Confirm queries for this command.
No (N): Do not perform the action.
No to All (L): Do not perform any actions and suppress subsequent
Confirm queries for this command.
Suspend (S): Pause the command and create a temporary session.
Help (?) Display help for these options.
A opção Suspender coloca o comando em espera e cria uma sessão aninhada temporária na qual você pode trabalhar até estar pronto para escolher uma opção de confirmação. O prompt de comando para a sessão aninhada tem dois sinais de interpolação extras (>>) para indicar que se trata de uma operação filho do comando pai original. Você pode executar comandos e scripts na sessão aninhada. Para encerrar a sessão aninhada e retornar para as opções de confirmação para o comando original, digite "exit".
No exemplo a seguir, a opção Suspender (S) é usada para interromper um comando temporariamente enquanto o usuário verifica a ajuda para um parâmetro de comando. Depois de obter as informações necessárias, o usuário digita "exit" para encerrar o prompt aninhado e, em seguida, seleciona a resposta Sim (s) para a consulta de confirmação.
PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm
Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): s
PS C:\ps-test>>> Get-Help New-Item -Parameter ItemType
-ItemType <string>
Specifies the provider-specified type of the new item.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
PS C:\ps-test>>> exit
Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y
Directory: C:\ps-test
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 8/27/2010 2:41 PM 0 test.txt
PALAVRAS-CHAVE
about_Common_Parameters
CONSULTE TAMBÉM
about_Preference_Variables
Write-Debug
Write-Warning
Write-Error
Write-Verbose