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 de cmdlets 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 um efeito sobre todos os cmdlets. Por exemplo, se um cmdlet não gerar nenhuma saída detalhada, usar o Verbose parâmetro Common não terá nenhum efeito.

Os parâmetros comuns também estão disponíveis em funções avançadas que usam o atributo CmdletBinding ou o atributo de parâmetro .

Vários parâmetros comuns substituem os padrões ou as 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 eles são usados.

Para obter mais informações, consulte about_Preference_Variables.

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

  • Debug únicas
  • Erroaction (ea)
  • ErrorVariable (EV)
  • Informationaction (infa)
  • InformationVariable (IV)
  • Outvariance (OV)
  • OutBuffer (OB)
  • PipelineVariable (PV)
  • Verbose VB
  • Avisoaction (WA)
  • WarningVariable (WV)

Os parâmetros de ação são valores de tipo preferência . Preferência é 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 o 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:

  • WhatIf (Wi)
  • Confirm CF

Descrições de parâmetros comuns

-Debug

Exibe detalhes no nível do programador sobre a operação feita 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 mensagens de depuração não são exibidas porque o valor da $DebugPreference variável é SilentlyContinue.

No modo interativo, o Debug parâmetro substitui o valor da $DebugPreference variável para o comando atual, definindo o valor de $DebugPreference como inquire.

No modo não interativo, o Debug parâmetro substitui o valor da $DebugPreference variável para o comando atual, definindo o valor de $DebugPreference para 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.

-ErrorAction

Determina como o cmdlet responde a um erro de não finalização do comando. Esse parâmetro funciona somente quando o comando gera um erro de não finalização, como os do Write-Error 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 valor da $ErrorActionPreference variável para o comando atual. Como o valor padrão da $ErrorActionPreference variável é 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 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:Break Entra no depurador quando ocorre um erro ou uma exceção é gerada.

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

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

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

-ErrorAction:SilentlyContinue suprime a mensagem de erro e continua executando o comando.

-ErrorAction:Stop exibe a mensagem de erro e para a execução do comando.

-ErrorAction: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 valor da variável de $ErrorAction preferência quando o parâmetro é usado em um comando para executar um script ou uma função.

-ErrorVariable

O ErrorVariable armazena mensagens de erro sobre o comando na variável especificada e na $Error variável automática. Para obter mais informações, confira about_Automatic_Variables

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 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 todos os erros nela:

Get-Process -Id 6 -ErrorVariable a

O comando a seguir adiciona todas as 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 contém apenas mensagens de erro de comandos específicos e não afeta o comportamento da $Error variável automática. A $Error variável automática 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 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 aninhadas ou scripts.

-Informationaction

Introduzido no PowerShell 5,0. No comando ou script em que é usado, o parâmetro Common informationaction substitui o valor da $InformationPreference variável de preferência, que por padrão é definido como SilentlyContinue. Quando você usa o 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 o $InformationPreference , consulte about_Preference_Variables.

Type: ActionPreference
Aliases: ia
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

-InformationAction:Break Insere o depurador em uma ocorrência do Write-Information comando.

-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, ignorar se esquece completamente da mensagem informativa; Ele não adiciona a mensagem informativa ao fluxo de informações.

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

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

-InformationAction:Suspend Não tem suporte no PowerShell 6 e superior, pois ele 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 valor da variável de $InformationAction preferência quando o parâmetro é usado em um comando para executar um script ou uma função.

-InformationVariable

Introduzido no PowerShell 5,0. No comando ou script em que é 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, as cadeias de caracteres serão Write-Information mostradas dependendo do valor da variável $InformationPreference de preferência. Para obter mais informações sobre $InformationPreference , consulte about_Preference_Variables.

Observação

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

Type: String
Aliases: iv

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-OutBuffer

Determina o número de objetos a acumular em um buffer antes que qualquer objeto seja enviado por meio do pipeline. Se você omitir esse parâmetro, os objetos serão enviados conforme eles 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 .

As alternativas de exemplo a seguir são exibidas entre ForEach-Object blocos de 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

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 a mais ( ) antes + do nome da variável.

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

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 conteúdo da $out variável:

$out

Observação

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

-PipelineVariable

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

Observação

As funções avançadas podem ter até três blocos de script: begin process , e 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 conforme a função é executado. 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.

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

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

No terceiro comando, os resultados dos dois primeiros comandos canalizados, representados pelas variáveis Left e Right , são processados usando um Foreach-Object Foreach-Object operador de multiplicação. O comando instrui os objetos armazenados nas variáveis Left e Right a serem multiplicados e especifica que os resultados devem ser exibidos como "Membro do intervalo esquerdo * Membro do intervalo à 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
...

-Verbose

Exibe informações detalhadas sobre a operação feita pelo comando . Essas informações se assemelham às informações em um rastreamento ou em um log de transações. Esse 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 .

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 valor da $VerbosePreference variável para o comando atual. Como o valor padrão da $VerbosePreference variável é 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 esse parâmetro quando o valor $VerbosePreference de não for SilentlyContinue (o padrão).

-WarningAction

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 valor da $WarningPreference variável para o comando atual. Como o valor padrão da variável é Continuar , os avisos são exibidos e a execução continua, a menos que $WarningPreference você use o parâmetro WarningAction.

-WarningAction:Break entra no depurador quando ocorre um aviso.

-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. Esse valor raramente é usado.

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

-WarningAction: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 valor da variável de preferência quando o parâmetro é usado em um comando para executar um $WarningAction script ou função.

-WarningVariable

Armazena avisos 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 ao usuário.

Para anexar os avisos ao conteúdo da variável, em vez de substituir os avisos que podem já estar armazenados lá, digite um sinal de a mais ( ) antes do + nome da variável.

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

Get-Process -Id 6 -WarningVariable a

O comando a seguir adiciona todos os 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 contém apenas avisos de comandos específicos. Você pode usar notação de matriz, como $a[0] ou para se referir a $warning[1,2] 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 executar o comando.

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 valor da $WhatIfPreference 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

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

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

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

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 valor da $ConfirmPreference variável para o comando atual. O valor padrão é true. Para obter mais informações, consulte 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 $ConfirmPreference estimado do cmdlet.

Por exemplo, o comando a seguir usa o Confirm parâmetro com um comando Remove-Item . 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 opções a seguir:

Resposta Resultado
Yes (Y) Execute a ação.
Yes to All (A) Executar todas as ações e suprimir Confirm consultas subsequentes
para este comando.
No (N): Não execute a ação.
No to All (L): Não executar nenhuma ação e suprimir subsequentes Confirm
consultas para este comando.
Suspend (S): Pause o comando e crie uma sessão temporária.
Help (?) Exibir 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 Confirm opção. O prompt de comando para a sessão aninhada tem dois pontos de >> 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 às Confirm opções 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 finalizar o prompt aninhado e, em seguida, seleciona a resposta Sim (y) à 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

Palavras-chave

about_Common_Parameters

Confira também

about_Preference_Variables

GraváDebug

Write-Warning

Write-Error

GraváVerbose