Sobre CommonParameters

BREVE DESCRIÇÃO

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 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 eles podem não ter efeito em todos os cmdlets. Por exemplo, se um cmdlet não gerar nenhuma saída detalhada, o uso do parâmetro Verbose common 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 os padrões ou preferências do sistema que você define usando as variáveis de preferência do 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 WhatIf e Confirm risk mitigation. Os cmdlets que envolvem risco para o sistema ou para os dados do usuário geralmente oferecem esses parâmetros.

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

• Depurar (db)
• ErrorAction (ea)
• ErrorVariable (ev)
• InformaçãoAção (infa)
• InformationVariable (iv)
• OutVariable (ov)
• OutBuffer (ob)
• PipelineVariable (pv)
• Verbose (vb)
• WarningAction (wa)
• WarningVariable (wv)

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

• WhatIf (wi)
• Confirmar (cf)

Para obter mais informações, consulte sobre_Variáveis_de_Preferência.

DESCRIÇÕES DE PARÂMETROS COMUNS

Depurar

O alias para Debug é db.

Exibe detalhes no nível do programador sobre a operação feita pelo comando. Este parâmetro funciona somente quando o comando gera uma mensagem de depuração. Por exemplo, esse parâmetro funciona quando um comando contém o Write-Debug cmdlet.

O parâmetro Debug substitui o $DebugPreference valor da variável para o comando atual, definindo o valor de $DebugPreferenceContinue. Como o valor padrão da variável é $DebugPreference, as mensagens de depuração não são exibidas por padrão.

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

ErrorAction

O alias para ErrorAction é ea.

Determina como o cmdlet responde a um erro de não terminação do comando. Esse parâmetro funciona somente quando o comando gera um erro não terminativo, como os Write-Error do cmdlet.

O parâmetro ErrorAction substitui o $ErrorActionPreference valor da variável para o comando atual. Como o valor padrão da variável é $ErrorActionPreference, 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 efeito sobre erros de encerramento (como dados ausentes, parâmetros que não são válidos ou permissões insuficientes) que impedem que um comando seja concluído com êxito.

-ErrorAction:Continue Exiba a mensagem de erro e continue executando o comando. Continue é o padrão.

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

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

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

-ErrorAction:Stop Exibe a mensagem de erro e para de executar o comando.

-ErrorAction:Suspend não é suportado no PowerShell Core, pois só está disponível para fluxos de trabalho.

Observação

O parâmetro ErrorAction substitui, mas não substitui o $ErrorAction valor da variável de preferência quando o parâmetro é usado em um comando para executar um script ou função.

ErrorVariable

O alias para ErrorVariable é ev.

ErrorVariable armazena mensagens de erro sobre o comando na variável especificada e na $Error variável 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 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 $a variável e, em seguida, armazena quaisquer erros nela:

Get-Process -Id 6 -ErrorVariable a

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

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

InformaçãoAcção

O alias para InformationAction é ia.

Introduzido no PowerShell 5.0. Dentro do comando ou script no qual é usado, o parâmetro comum InformationAction substitui o valor da variável de $InformationPreference preferência, que por padrão é definida como SilentlyContinue. Quando você usa Write-Information em um script com InformationAction, Write-Information os valores são mostrados dependendo do valor do parâmetro InformationAction . Para obter mais informações sobre $InformationPreference, consulte about_Preference_Variables.

-InformationAction:Stop Interrompe um comando ou script em uma ocorrência do Write-Information comando.

-InformationAction:Ignore suprime a mensagem informativa e continua executando o comando. Ao contrário de SilentlyContinue, Ignore esquece completamente a mensagem informativa; ele não adiciona a mensagem informativa ao fluxo de informações.

-InformationAction:Inquire Exibe a mensagem informativa especificada em um Write-Information comando e pergunta se você deseja continuar.

-InformationAction:Continue Exibe a mensagem informativa e continua em execução.

-InformationAction:Suspend não é suportado no PowerShell Core, pois só está disponível para fluxos de trabalho.

-InformationAction:SilentlyContinue nenhum efeito, pois a mensagem informativa não é exibida (padrão) e o script continua sem interrupção.

Observação

O parâmetro InformationAction substitui, mas não substitui o $InformationAction valor da variável de preferência quando o parâmetro é usado em um comando para executar um script ou função.

InformationVariable

O alias para InformationVariable é iv.

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

OutBuffer

O alias para OutBuffer é ob e usa um valor System.Int32 .

Determina o número de objetos a serem acumulados em um buffer antes que quaisquer objetos sejam enviados pelo pipeline. Se você omitir esse parâmetro, os objetos serão enviados à medida que forem gerados.

Este parâmetro de gerenciamento de recursos foi projetado para usuários avançados. Quando você usa esse parâmetro, o PowerShell envia dados para o próximo cmdlet em lotes de OutBuffer + 1.

O exemplo a seguir alterna exibições entre blocos de ForEach-Object processo que usam o Write-Host cmdlet. A exibição 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 alias para OutVariable é ov.

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

Para adicionar a saída à variável, em vez de substituir qualquer saída que já esteja armazenada lá, digite um sinal de adição (+) antes do nome da variável.

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

Get-Process PowerShell -OutVariable out

O comando a seguir adiciona o objeto process à $out variável:

Get-Process iexplore -OutVariable +out

O comando a seguir exibe o conteúdo da $out variável:

$out

Observação

A variável criada pelo parâmetro OutVariable é um [System.Collections.ArrayList]arquivo .

PipelineVariable

O alias para PipelineVariable é pv e usa um valor de cadeia de caracteres .

PipelineVariable armazena o valor do elemento de pipeline atual como uma variável, para qualquer comando nomeado à medida que flui pelo pipeline.

Os valores válidos são cadeias de caracteres, o mesmo que para qualquer nome de variável.

A seguir está um exemplo de como PipelineVariable funciona. Neste exemplo, o parâmetro PipelineVariable é adicionado a um Foreach-Object comando para armazenar os resultados do comando em variáveis. Um intervalo de números, de 1 a 10, é canalizado para o primeiro Foreach-Object comando, cujos resultados são armazenados em uma variável chamada Left.

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

No terceiro Foreach-Object comando, os resultados dos dois Foreach-Object primeiros comandos canalizados, representados pelas variáveis Left e Right, são processados usando 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 exibidos como "Membro do intervalo esquerdo * Membro do intervalo direito = 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

O alias para Verbose é vb.

Exibe informações detalhadas sobre a operação feita pelo comando. Essas informações são semelhantes às informações em um rastreamento ou em um log de transações. Este parâmetro funciona somente quando o comando gera uma mensagem detalhada. Por exemplo, esse parâmetro funciona quando um comando contém o Write-Verbose cmdlet.

O parâmetro Verbose substitui o $VerbosePreference valor da variável 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.

-Verbose:$true tem o mesmo efeito que -Verbose

-Verbose:$false suprime a exibição de mensagens detalhadas. Use este parâmetro quando o valor de $VerbosePreference não for SilentlyContinue (o padrão).

AvisoAção

O alias para WarningAction é wa.

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

O parâmetro WarningAction substitui o $WarningPreference valor da variável para o comando atual. Como o valor padrão da variável é $WarningPreference, os avisos são exibidos e a execução continua, a menos que você use o parâmetro WarningAction.

-WarningAction:Continue exibe as mensagens de aviso e continua executando o comando. Continue é o padrão.

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

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

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

Observação

O parâmetro WarningAction substitui, mas não substitui o $WarningAction valor da variável de preferência quando o parâmetro é usado em um comando para executar um script ou função.

WarningVariable

O alias para WarningVariable é wv.

Armazena avisos sobre o comando na variável especificada.

Todos os avisos gerados são salvos na variável, mesmo que os avisos não sejam exibidos para o usuário.

Para acrescentar os avisos ao conteúdo da variável, em vez de substituir os avisos que já possam estar armazenados lá, digite um sinal de adição (+) antes do nome da variável.

Por exemplo, o comando a seguir cria a $a variável e, em seguida, armazena todos os avisos nela:

Get-Process -Id 6 -WarningVariable a

O comando a seguir adiciona avisos à $a variável:

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 contenha apenas avisos de comandos específicos. Você pode usar notação de matriz, como $a[0] ou $warning[1,2] para fazer referência a avisos específicos armazenados na variável.

Observação

O parâmetro WarningVariable não captura avisos de chamadas aninhadas em funções ou scripts.

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

E se

O alias para WhatIf é wi.

Exibe uma mensagem que descreve o efeito do comando, em vez de executá-lo.

O parâmetro WhatIf substitui o $WhatIfPreference valor da variável para o comando atual. Como o valor padrão da variável é 0 (desabilitado), o $WhatIfPreference comportamento WhatIf não é feito sem o parâmetro WhatIf . Para obter mais informações, digite o seguinte comando:

Get-Help about_Preference_Variables

-WhatIf:$true tem o mesmo efeito que -WhatIf.

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

Por exemplo, o comando a seguir usa o -WhatIf parâmetro em um Remove-Item comando:

Remove-Item Date.csv -WhatIf

Em vez de remover o item, o 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 alias para Confirm é cf.

Solicita confirmação antes de executar o comando.

O parâmetro Confirm substitui o $ConfirmPreference valor da variável para o comando atual. O valor padrão é true. Para obter mais informações, digite o seguinte comando:

Get-Help about_Preference_Variables

-Confirm:$true tem o mesmo efeito que -Confirm.

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

Por exemplo, o comando a seguir usa o parâmetro Confirm com um Remove-Item comando. Antes de remover o item, o PowerShell lista as operações que faria e os itens que seriam afetados e solicita 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 Confirmar resposta são as seguintes:

Resposta	Resultado
Sim (Y)	Execute a ação.
Sim a Todos (A)	Executar todas as ações e suprimir consultas Confirmar subsequentes
	para este comando.
N.o (N):	Não execute a ação.
Não a Todos (L):	Não execute nenhuma ação e suprima Confirmar subsequente
	consultas para este comando.
Suspensão (S):	Pause o comando e crie uma sessão temporária.
Ajuda (?)	Exiba ajuda para essas opções.

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 Confirmar . O prompt de comando para a sessão aninhada tem dois acento circunflexos (>>) para indicar que é 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 às opções de confirmação do 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 (y) para a 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

sobre_Variáveis_de_Preferência

Gravação-depuração

Escrever-Aviso

Erro de Gravação

Escrever-Verbose