Sobre os CommonParameters

BREVE DESCRIÇÃO

Descreve os parâmetros que podem ser usados com qualquer cmdlet.

LONGA DESCRIÇÃO

Os parâmetros comuns são um conjunto de parâmetros de cmdlet que pode usar com qualquer cmdlet. São implementados pela PowerShell, não pelo desenvolvedor de cmdlet, e estão automaticamente disponíveis para qualquer cmdlet.

Pode utilizar os parâmetros comuns com qualquer cmdlet, mas podem não ter um efeito em todos os cmdlets. Por exemplo, se um cmdlet não gerar qualquer saída verbose, usar o parâmetro comum Verbose não tem efeito.

Os parâmetros comuns também estão disponíveis em funções avançadas que utilizam o atributo CmdletBinding ou o atributo Parâmetro, e em todos os fluxos de trabalho.

Vários parâmetros comuns substituem as predefinições ou preferências do sistema que definiu utilizando as variáveis de preferência PowerShell. Ao contrário das variáveis preferenciais, os parâmetros comuns afetam apenas os comandos em que são usados.

Além dos parâmetros comuns, muitos cmdlets oferecem os parâmetros de mitigação de riscos WhatIf e Confirme. Os cmdlets que envolvem risco para o sistema ou para os dados do utilizador geralmente oferecem estes parâmetros.

A lista a seguir apresenta os parâmetros comuns. Os seus pseudónimos estão listados em parênteses.

• Debug (db)
• ErrorAction (ea)
• ErroVariável (ev)
• InformationAction (infa)
• Informação Variavel (iv)
• OutVariable (ov)
• OutBuffer (ob)
• PipelineVariable (pv)
• Verbose (vb)
• AdvertênciaAcção (wa)
• AdvertênciaVariável (wv)

Os parâmetros de mitigação do risco são:

• WhatIf (wi)
• Confirmar (cf)

Para mais informações, consulte about_Preference_Variables.

DESCRIÇÕES DE PARÂMETROS COMUNS

Depurar

O pseudónimo de Debug é db.

Apresenta detalhes ao nível do programador sobre a operação efetuada pelo comando. Este parâmetro só funciona quando o comando gera uma mensagem de depurativa. Por exemplo, este parâmetro funciona quando um comando contém o Write-Debug cmdlet.

O parâmetro Debug sobrepõe-se ao valor da $DebugPreference variável para o comando atual, definindo o valor de $DebugPreference Continuar. Como o valor padrão da $DebugPreference variável é SilentlyContinue, as mensagens de depuração não são apresentadas por padrão.

-Debug:$truetem o mesmo efeito -Debug que . Utilize -Debug:$false para suprimir a exibição de mensagens de depuração quando não é $DebugPreference SilentlyContinue, que é o padrão.

ErrorAction

O pseudónimo de ErrorAction é ea.

Determina como o cmdlet responde a um erro não-terminal do comando. Este parâmetro só funciona quando o comando gera um erro não-terminal, como os do Write-Error cmdlet.

O parâmetro ErrorAction sobrepõe-se ao valor da $ErrorActionPreference variável para o comando atual. Como o valor predefinido da $ErrorActionPreference variável é Continuar, as mensagens de erro são apresentadas e a execução continua a menos que utilize o parâmetro ErrorAction.

O parâmetro ErrorAction não tem qualquer efeito no fim de erros (tais como dados em falta, parâmetros que não são válidos, ou permissões insuficientes) que impedem que um comando complete com sucesso.

-ErrorAction:Continuemostrar a mensagem de erro e continuar a executar o comando. Continue é a predefinição.

-ErrorAction:Ignoresuprime a mensagem de erro e continua a executar o comando. Ao contrário do SilentlyContinue, o Ignore não adiciona a mensagem de erro à $Error variável automática. O valor Ignore é introduzido no PowerShell 3.0.

-ErrorAction:Inquireexibe a mensagem de erro e solicita-lhe confirmação antes de continuar a execução. Este valor raramente é usado.

-ErrorAction:SilentlyContinuesuprime a mensagem de erro e continua a executar o comando.

-ErrorAction:Stopexibe a mensagem de erro e deixa de executar o comando.

-ErrorAction:Suspendnão é suportado no PowerShell Core, uma vez que só está disponível para fluxos de trabalho.

ErroVariável

O pseudónimo de ErrorVariable é ev.

ErrorVariable armazena mensagens de erro sobre o comando na variável especificada e na $Error variável automática. Para mais informações, digite o seguinte comando:

Get-Help about_Automatic_Variables

Por predefiniçã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 variável, escreva um sinal de mais + () antes do nome variável.

Por exemplo, o seguinte comando cria a $a variável e, em seguida, armazena quaisquer erros nela:

Get-Process -Id 6 -ErrorVariable a

O seguinte comando adiciona quaisquer mensagens de erro à $a variável:

Get-Process -Id 2 -ErrorVariable +a

O seguinte comando mostra o conteúdo $a de:

$a

Pode utilizar este parâmetro para criar uma variável que contém apenas mensagens de erro de comandos específicos. A $Error variável automática contém mensagens de erro de todos os comandos da sessão. Pode utilizar a notação de matriz, como $a[0] ou para se referir a $error[1,2] erros específicos armazenados nas variáveis.

InformaçãoAcção

O pseudónimo de InformationAction é ia.

Introduzido no PowerShell 5.0. Dentro do comando ou script em que é utilizado, o parâmetro comum InformationAction sobrepõe-se ao valor da $InformationPreference variável de preferência, que por padrão é definida como SilentlyContinue. Quando utiliza Write-Information num script com InformationAction, Write-Information os valores são apresentados em função do valor do parâmetro InformationAction. Para mais informações $InformationPreference sobre , consulte about_Preference_Variables.

-InformationAction:Stoppara um comando ou script numa ocorrência do Write-Information comando.

-InformationAction:Ignoresuprime a mensagem informativa e continua a executar o comando. Ao contrário do SilentlyContinue, ignore completamente a mensagem informativa; não adiciona a mensagem informativa ao fluxo de informação.

-InformationAction:Inquireexibe a mensagem informativa que especifica num comando e, em Write-Information seguida, pergunta se pretende continuar.

-InformationAction:Continueexibe a mensagem informativa e continua a funcionar.

-InformationAction:Suspendnão é suportado no PowerShell Core, uma vez que só está disponível para fluxos de trabalho.

-InformationAction:SilentlyContinuenenhum efeito, uma vez que a mensagem informacional não é exibida (Predefinido) e o script continua sem interrupção.

Informação Variavel

O pseudónimo de Informação Variavel é iv.

Introduzido no PowerShell 5.0. Dentro do comando ou script no qual é utilizado, o parâmetro comum InformationVariable armazena numa variável uma cadeia que especifica adicionando o Write-Information comando. Write-Informationos valores são apresentados em função do valor do parâmetro comum InformationAction; se não adicionar o parâmetro comum InformationAction, Write-Information as cordas são mostradas dependendo do valor da $InformationPreference variável de preferência. Para mais informações $InformationPreference sobre , consulte about_Preference_Variables.

OutBuffer

O pseudónimo de OutBuffer é ob e tem um valor System.Int32.

Determina o número de objetos a acumular num tampão antes de quaisquer objetos serem enviados através do oleoduto. Se omitir este parâmetro, os objetos são enviados à medida que são gerados.

Este parâmetro de gestão de recursos foi concebido para utilizadores avançados. Quando utiliza este parâmetro, o PowerShell envia dados para o próximo cmdlet em lotes de OutBuffer + 1 .

O exemplo a seguir alterna os ecrãs entre os ForEach-Object blocos de processo que utilizam o Write-Host cmdlet. O visor alterna em lotes de 2 ou OutBuffer + 1 .

1..4 | ForEach-Object {
        Write-Host "$($_): First"; $_
      } -OutBuffer 1 | ForEach-Object {
                        Write-Host "$($_): Second" }

1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second

OutVariable

O pseudónimo de OutVariable é ov.

Armazena objetos de saída do comando na variável especificada, além de enviar a saída ao longo do oleoduto.

Para adicionar a saída à variável, em vez de substituir qualquer saída que já possa ser armazenada lá, digite um sinal de mais + () antes do nome variável.

Por exemplo, o seguinte comando cria a $out variável e armazena o objeto de processo nele:

Get-Process PowerShell -OutVariable out

O seguinte comando adiciona o objeto do processo à $out variável:

Get-Process iexplore -OutVariable +out

O seguinte comando mostra o conteúdo da $out variável:

$out

PipelineVariable

O pseudónimo de PipelineVariable é pv e tem um valor de corda.

PipelineVariable armazena o valor do elemento de gasoduto atual como variável, para qualquer comando nomeado à medida que flui através do gasoduto.

Valores válidos são cordas, o mesmo que para qualquer nome variável.

Segue-se um exemplo de como funciona o PipelineVariable. Neste exemplo, o parâmetro PipelineVariable é adicionado a um Foreach-Object comando para armazenar os resultados do comando em variáveis. Uma gama de números, de 1 a 10, são canalizados para o primeiro Foreach-Object comando, dos quais os resultados são armazenados numa variável chamada Esquerda.

Os resultados do primeiro Foreach-Object comando são canalizados para um segundo Foreach-Object comando, que filtra os objetos devolvidos pelo primeiro Foreach-Object comando. Os resultados do segundo comando são armazenados numa variável chamada Right.

No terceiro Foreach-Object comando, os resultados dos dois Foreach-Object primeiros comandos canalizados, representados pelas variáveis Esquerda e Direita, são processados através de um operador de multiplicação. O comando instrui os objetos armazenados nas variáveis Esquerda e Direita a serem multiplicados e especifica que os resultados devem ser apresentados como "Membro da gama esquerda * Membro da gama direita = 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
...

Verboso

O pseudónimo de Verbose é vb.

Apresenta informações detalhadas sobre a operação feita pelo comando. Esta informação assemelha-se à informação num vestígio ou num registo de transações. Este parâmetro só funciona quando o comando gera uma mensagem verbose. Por exemplo, este parâmetro funciona quando um comando contém o Write-Verbose cmdlet.

O parâmetro Verbose sobrepõe-se ao valor da $VerbosePreference variável para o comando atual. Como o valor padrão da $VerbosePreference variável é SilentlyContinue, as mensagens verbosas não são exibidas por padrão.

-Verbose:$truetem o mesmo efeito que-Verbose

-Verbose:$falsesuprime a exibição de mensagens verbosas. Utilize este parâmetro quando o valor de $VerbosePreference não é SilentlyContinue (o padrão).

Advertência

O pseudónimo de WarningAction é wa.

Determina como o cmdlet responde a um aviso do comando. Continuar é o valor padrão. Este parâmetro só funciona quando o comando gera uma mensagem de aviso. Por exemplo, este parâmetro funciona quando um comando contém o Write-Warning cmdlet.

O parâmetro WarningAction sobrepõe-se ao valor da $WarningPreference variável para o comando atual. Como o valor predefinido da $WarningPreference variável é Continuar, as advertências são apresentadas e a execução continua a menos que utilize o parâmetro WarningAction.

-WarningAction:Continueexibe as mensagens de aviso e continua a executar o comando. Continue é a predefinição.

-WarningAction:Inquireexibe a mensagem de aviso e solicita-lhe confirmação antes de continuar a execução. Este valor raramente é usado.

-WarningAction:SilentlyContinuesuprime a mensagem de aviso e continua a executar o comando.

-WarningAction:Stopexibe a mensagem de aviso e para de executar o comando.

AdvertênciaVariável

O pseudónimo de WarningVariable é wv.

Armazena avisos sobre o comando na variável especificada.

Todos os avisos gerados são guardados na variável mesmo que os avisos não sejam apresentados ao utilizador.

Para anexar as advertências ao conteúdo variável, em vez de substituir quaisquer avisos que possam já estar armazenados lá, digite um sinal de mais + () antes do nome variável.

Por exemplo, o seguinte comando cria a $a variável e, em seguida, armazena quaisquer avisos nele:

Get-Process -Id 6 -WarningVariable a

O seguinte comando adiciona quaisquer avisos à $a variável:

Get-Process -Id 2 -WarningVariable +a

O seguinte comando mostra o conteúdo $a de:

$a

Pode utilizar este parâmetro para criar uma variável que contenha apenas avisos de comandos específicos. Pode utilizar a notação de matriz, como $a[0] ou para se referir a $warning[1,2] avisos específicos armazenados na variável.

Descrições dos parâmetros de gestão de risco

WhatIf

O pseudónimo para o WhatIf é wi.

Exibe uma mensagem que descreve o efeito do comando, em vez de executar o comando.

O parâmetro WhatIf sobrepõe-se ao valor da $WhatIfPreference variável para o comando atual. Como o valor padrão da $WhatIfPreference variável é 0 (desativado), o comportamento whatif não é feito sem o parâmetro WhatIf. Para mais informações, digite o seguinte comando:

Get-Help about_Preference_Variables

-WhatIf:$truetem o mesmo efeito -WhatIf que .

-WhatIf:$falsesuprime o comportamento automático WhatIf que resulta quando o valor da $WhatIfPreference variável é 1.

Por exemplo, o seguinte comando utiliza o -WhatIf parâmetro num Remove-Item comando:

Remove-Item Date.csv -WhatIf

Em vez de remover o item, a PowerShell lista as operações que faria e os itens que seriam afetados. Este comando produz a seguinte saída:

What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".

Confirmar

O pseudónimo de Confirmar é cf.

Solicita-lhe confirmação antes de executar o comando.

O parâmetro Confirmar sobrepõe-se ao valor da $ConfirmPreference variável para o comando atual. O valor predefinido é true. Para mais informações, digite o seguinte comando:

Get-Help about_Preference_Variables

-Confirm:$truetem o mesmo efeito -Confirm que .

-Confirm:$falsesuprime a confirmação automática, que ocorre quando o valor de $ConfirmPreference é inferior ou igual ao risco estimado do cmdlet.

Por exemplo, o seguinte comando utiliza o parâmetro Confirmar com um Remove-Item comando. Antes de remover o item, a PowerShell lista as operações que faria e os itens que seriam afetados e pede aprovação.

PS C:\ps-test> Remove-Item tmp*.txt -Confirm

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

As opções de resposta confirmar são as seguintes:

A opção Suspender coloca o comando em espera e cria uma sessão temporária aninhada na qual pode trabalhar até estar pronto para escolher uma opção Confirmar. O pedido de comando para a sessão aninhada tem duas caretas extra (>>) para indicar que é uma operação infantil do comando original dos pais. Pode executar comandos e scripts na sessão aninhada. Para terminar a sessão aninhada e voltar às opções Confirmar para o comando original, escreva "saída".

No exemplo seguinte, a opção Suspender (S) é utilizada para interromper temporariamente um comando enquanto o utilizador verifica a ajuda de um parâmetro de comando. Depois de obter as informações necessárias, os tipos de utilizador "sair" para terminar a solicitação aninhada e, em seguida, selecionam a resposta Sim (y) à consulta Confirmar.

PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm

Confirm
Are you sure you want to perform this action?

Performing operation "Create File" on Target "Destination:
C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default
is "Y"): s

PS C:\ps-test> Get-Help New-Item -Parameter ItemType

-ItemType <string>
Specifies the provider-specified type of the new item.

Required?                    false
Position?                    named
Default value
Accept pipeline input?       true (ByPropertyName)
Accept wildcard characters?  false

PS C:\ps-test> exit

Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test
.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (defau
lt is "Y"): y

Directory: C:\ps-test

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         8/27/2010   2:41 PM          0 test.txt

PALAVRAS-CHAVE

about_Common_Parameters

VER TAMBÉM

about_Preference_Variables

Write-Debug

Aviso de escrita

Erro de escrita

Write-Verbose