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 pelo PowerShell, não pelo desenvolvedor do cmdlet, e estão 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 verbose saída, o uso do Verbose parâmetro common não terá efeito.

Os parâmetros comuns também estão disponíveis em funções avançadas que usam o CmdletBinding atributo ou o Parameter atributo. Quando você usa esses atributos, o PowerShell adiciona automaticamente os Parâmetros Comuns. Você não pode criar parâmetros que usem os mesmos nomes que os Parâmetros comuns.

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.

Para obter mais informações, consulte about_Preference_Variables.

A lista a seguir exibe os parâmetros comuns. Seus apelidos estão listados entre parênteses.

• Debug (db)
• ErrorAction (ea)
• Variável de erro (ev)
• InformationAction (infa)
• Variável de informação (iv)
• OutVariable (ov)
• OutBuffer (ob)
• Variável de pipeline (pv)
• ProgressAction (proga)
• Verbose (vb)
• Ação de Advertência (wa)
• Variável de aviso (wv)

Os parâmetros Action são valores do tipo ActionPreference . ActionPreference é uma enumeração com os seguintes valores:

Nome	Valor
Break	6
Suspend	5
Ignore	4
Inquire	3
Continue	2
Stop	1
SilentlyContinue	0

Você pode usar o nome ou o valor com o parâmetro.

Além dos parâmetros comuns, muitos cmdlets oferecem parâmetros de mitigação de risco. Os cmdlets que envolvem risco para o sistema ou para os dados do usuário geralmente oferecem esses parâmetros.

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

• E se (wi)
• Confirm (cf)

Descrições de parâmetros comuns

-Debug

Exibe detalhes no nível do programador sobre a operação realizada pelo comando. Esse 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.

Type: SwitchParameter
Aliases: db
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

Por padrão, as $DebugPreference mensagens de depuração não são exibidas porque o valor da variável é SilentlyContinue.

O Debug parâmetro substitui o $DebugPreference valor da variável para o comando atual, definindo o valor de $DebugPreference como Continuar.

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

-Ação de erro

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

Type: ActionPreference
Aliases: ea
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

O parâmetro ErrorAction substitui o $ErrorActionPreference valor da variável para o comando atual. Como o valor padrão da variável é Continue, as mensagens de erro são exibidas e a $ErrorActionPreference 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.

• Break Entra no depurador quando ocorre um erro ou uma exceção é gerada.
• Continue exibe a mensagem de erro e continua executando o comando. Continue é o padrão.
• Ignore Suprime a mensagem de erro e continua executando o comando. Ao contrário de SilentlyContinue, Ignore não adiciona a mensagem de erro à $Error variável automática. O valor Ignorar é introduzido no PowerShell 3.0.
• Inquire exibe a mensagem de erro e solicita a 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 só está disponível para fluxos de trabalho que não têm suporte no PowerShell 6 e posteriores.

Observação

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

-Variável de erro

Os registros de erro são armazenados automaticamente na $Error variável automática. Para obter mais informações, confira about_Automatic_Variables.

Quando você usa o parâmetro ErrorVariable em um comando, o PowerShell também armazena os registros de erro emitidos pelo comando na variável especificada pelo parâmetro.

Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Por padrão, novas mensagens de erro substituem as mensagens de erro que já estão armazenadas na variável. Para anexar a mensagem de erro ao conteúdo da variável, coloque um sinal de adição (+) antes do nome da variável.

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

Get-Process -Id 6 -ErrorVariable a

O comando a seguir adiciona 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 e não afete o $Error comportamento da variável automática. 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 se referir a erros específicos armazenados nas variáveis.

Observação

A variável de erro personalizada contém todos os erros gerados pelo comando, incluindo erros de chamadas para funções ou scripts aninhados.

-Ação de informação

Introduzido no PowerShell 5.0. No comando ou script no qual ele é 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 $InformationPreferenceo , consulte about_Preference_Variables.

Type: ActionPreference
Aliases: infa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

• Break Insere o depurador em uma ocorrência do Write-Information comando.
• Stop interrompe um comando ou script em uma ocorrência do Write-Information comando.
• 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.
• Inquire exibe a mensagem informativa especificada em um Write-Information comando e pergunta se deseja continuar.
• Continue exibe a mensagem informativa e continua em execução.
• Suspend não tem suporte no PowerShell 6 e superior, pois só está disponível para fluxos de trabalho.
• 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.

-Variável de informação

Introduzido no PowerShell 5.0. Quando você usa o parâmetro comum InformationVariable , os registros de informações são armazenados na variável especificada pelo parâmetro. E o cmdlet do PowerShell pode gravar registros de informações no fluxo de informações . Você também pode usar o Write-Information cmdlet para gravar registros de informações.

Os registros de informações são exibidos como mensagens no console por padrão. Você pode controlar a exibição do registro de informações usando o parâmetro comum InformationAction . Você também pode alterar o comportamento usando a $InformationPreference variável de preferência. Para obter mais informações sobre $InformationPreferenceo , consulte about_Preference_Variables.

Observação

A variável information contém todas as mensagens de informações geradas pelo comando, incluindo mensagens de informações de chamadas para funções aninhadas ou scripts.

Type: String
Aliases: iv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Por padrão, o novo registro de informações substitui os valores que já estão armazenados na variável. Para anexar a mensagem de erro ao conteúdo da variável, coloque um sinal de adição (+) antes do nome da variável.

-Buffer de saída

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

Type: Int32
Aliases: ob
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Esse 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 para ForEach-Object processar blocos 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

-Variável de saída

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

Type: String
Aliases: ov
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Para adicionar a saída à variável, em vez de substituir qualquer saída que já possa estar 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 de processo à $out variável:

Get-Process iexplore -OutVariable +out

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

$out

Observação

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

-Variável de pipeline

PipelineVariable permite o acesso ao valor mais recente passado para o próximo segmento de pipeline pelo comando que usa esse parâmetro. Qualquer comando no pipeline pode acessar o valor usando o PipelineVariable nomeado. O valor é atribuído à variável quando ela é passada para o próximo segmento do pipeline. Isso torna o PipelineVariable mais fácil de usar do que uma variável temporária específica, que pode precisar ser atribuída em vários locais.

Ao contrário $_ de ou $PSItem, o uso de um PipelineVariable permite que qualquer comando de pipeline acesse valores de pipeline passados (e salvos) por comandos diferentes do comando imediatamente anterior. Os comandos de pipeline podem acessar o último valor canalizado durante o processamento do próximo item que passa pelo pipeline. Isso permite que um comando retorne sua saída para um comando anterior (ou para si mesmo).

Observação

As funções avançadas podem ter até três blocos de script: begin, processe end. Ao usar o parâmetro PipelineVariable com funções avançadas, somente os valores do primeiro bloco de script definido são atribuídos à variável à medida que a função é executada. Para obter mais informações, consulte Funções avançadas. O PowerShell 7.2 corrige esse comportamento.

Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

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

Cuidado

O PipelineVariable tem como escopo o pipeline no qual ele é invocado. As variáveis fora do pipeline, que usam o mesmo nome, são limpas antes que o pipeline seja executado. O PipelineVariable sai do escopo quando o pipeline é encerrado. Se vários comandos dentro do pipeline especificarem a mesma PipelineVariable , haverá apenas uma variável compartilhada. Essa variável é atualizada com a saída canalizada mais recente do comando que especifica a variável.

Alguns comandos de bloqueio coletam todos os itens do pipeline antes de produzir qualquer saída, por exemplo Sort-Object , ou Select-Object -Last. Qualquer PipelineVariable atribuído em um comando antes desse comando de bloqueio sempre contém o item canalizado final do comando anterior quando usado em um comando após o comando de bloqueio.

Veja a seguir 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 5, é canalizado para o primeiro Foreach-Object comando, cujos resultados são armazenados em uma variável chamada $temp.

Os resultados do primeiro Foreach-Object comando são canalizados para um segundo Foreach-Object comando, que exibe os valores atuais de $temp e $_.

# Create a variable named $temp
$temp=8
Get-Variable temp
# Note that the variable just created isn't available on the
# pipeline when -PipelineVariable creates the same variable name
1..5 | ForEach-Object -PipelineVariable temp -Begin {
    Write-Host "Step1[BEGIN]:`$temp=$temp"
} -Process {
  Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
  Write-Output $_
} | ForEach-Object {
  Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
}
# The $temp variable is deleted when the pipeline finishes
Get-Variable temp

Name                           Value
----                           -----
temp                           8

Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
        Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
        Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
        Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
        Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
        Step2[PROCESS]:$temp=5 - $_=5

Name                           Value
----                           -----
temp

-Ação de progresso

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. O parâmetro ProgressAction foi adicionado no PowerShell 7.4.

O parâmetro ProgressAction usa um dos ActionPreference valores de enumeração: SilentlyContinue, Stop, Continue, Inquire, Ignore, , Suspendou Break.

Os valores válidos são os seguintes:

• Break Insere o depurador em uma ocorrência do Write-Progress comando.
• Stop: não exibe a barra de progresso. Em vez disso, ele exibe uma mensagem de erro e interrompe a execução.
• Inquire: 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.
• Continue: (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.

Type: ActionPreference
Aliases: proga
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

-Verbose

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

Type: SwitchParameter
Aliases: vb
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

O Verbose parâmetro substitui o $VerbosePreference valor da variável para o comando atual. Como o $VerbosePreference valor padrão da variável é SilentlyContinue, verbose as mensagens não são exibidas por padrão.

• -Verbose:$true tem o mesmo efeito que -Verbose
• -Verbose:$false Suprime a exibição de verbose mensagens. Use esse parâmetro quando o valor de $VerbosePreference não for SilentlyContinue (o padrão).

-Ação de aviso

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

Type: ActionPreference
Aliases: wa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

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

• Break entra no depurador quando ocorre um aviso.
• Continue exibe as mensagens de aviso e continua executando o comando. Continue é o padrão.
• Inquire exibe a mensagem de aviso e solicita a 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 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.

-Variável de aviso

Armazena registros de aviso sobre o comando na variável especificada.

Type: String
Aliases: wv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

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 quaisquer avisos que já possam estar armazenados lá, digite um sinal de mais (+) antes do nome da variável.

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

Get-Process -Id 6 -WarningVariable a

O comando a seguir adiciona quaisquer 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 a notação de matriz, como $a[0] ou $warning[1,2] para se referir a avisos específicos armazenados na variável.

Observação

A variável de aviso contém todos os avisos gerados pelo comando, incluindo avisos de chamadas para funções ou scripts aninhados.

Descrições de parâmetros de gerenciamento de risco

-WhatIf

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

Type: SwitchParameter
Aliases: wi
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

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

• $true tem o mesmo efeito que -WhatIf.
• $false suprime o comportamento automático WhatIf que resulta quando o $WhatIfPreference valor da 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 ele faria 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

Solicita sua confirmação antes de executar o comando.

Type: SwitchParameter
Aliases: cf
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

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

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

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

Resposta	Resultado
Yes (Y)	Execute a ação.
Yes to All (A)	Execute todas as ações e suprima as ações subsequentes Confirm
	consultas para este comando.
No (N):	Não execute a ação.
No to All (L):	Não execute nenhuma ação e suprima as ações subsequentes
	Confirm consultas para este comando.
Suspend (S):	Pause o comando e crie uma sessão temporária.
Help (?)	Exiba a 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é que esteja pronto para escolher uma Confirm opção. O prompt de comando da sessão aninhada tem dois acento circunflexo () extras 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 Confirm opções 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 de um parâmetro de comando. Depois de obter as informações necessárias, o usuário digita "exit" para encerrar o prompt aninhado e seleciona a resposta Sim (y) para a Confirm consulta.

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

Confira também

• about_Preference_Variables
• Escrever-Debug
• Write-Error
• Escrever-Verbose
• Write-Warning