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 efeito em todos os cmdlets. Por exemplo, se um cmdlet não gerar nenhuma saída detalhada, o uso do Verbose parâmetro comum 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 .
Vários parâmetros comuns substituem 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 aliases são listados entre parênteses.
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- Verbose (vb)
- WarningAction (wa)
- WarningVariable (wv)
Os parâmetros Action são valores de 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 riscos 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âmetro 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
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.
-Erroraction
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 aqueles 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 é Continuar, 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:Break
Insere o 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, Ignore não adiciona a mensagem de erro à $Error
variável automática. O valor 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 de executar o comando .
-ErrorAction:Suspend
só está disponível para fluxos de trabalho que não têm suporte no PowerShell 6 e além.
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 função.
-ErrorVariable
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 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 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. Dentro do 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 $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, 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 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 função.
-InformationVariable
Introduzido no PowerShell 5.0. Dentro do comando ou script no qual ele é 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 variável de $InformationPreference
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 aninhadas ou scripts.
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 serem acumulados em um buffer antes que qualquer objeto seja enviado pelo pipeline. Se você omitir esse parâmetro, os objetos serão enviados conforme eles forem 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 exibe entre os 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
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 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 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 chamado PipelineVariable. O valor é atribuído à variável quando ela é passada para o próximo segmento de 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
, usar 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 alimente sua saída para um comando anterior (ou a si mesmo).
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 é 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. Variáveis fora do pipeline, que usam o mesmo nome, são removidas antes que o pipeline seja executado. O PipelineVariable fica fora do escopo quando o pipeline é encerrado. Se vários comandos dentro do pipeline especificarem o mesmo 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 de 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 final canalizado do comando anterior quando usado em um comando após o comando de bloqueio.
Veja a seguir um exemplo de como o 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, são canalizados 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 is not 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
Get-Variable: Cannot find a variable with the name 'temp'.
-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 de $VerbosePreference
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 $WarningPreference
variável é Continuar, os avisos são exibidos e a execução continua, a menos que 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 para de executar o comando.
Observação
O parâmetro WarningAction substitui, mas não substitui o valor da variável de $WarningAction
preferência quando o parâmetro é usado em um comando para executar um 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 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 adição (+
) 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 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 aninhadas ou scripts.
Descrições de parâmetros de gerenciamento de riscos
-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 de 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 de WhatIf automático 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 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 $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 | Result |
---|---|
Yes (Y ) |
Execute a ação. |
Yes to All (A ) |
Executar todas as ações e suprimir consultas subsequentes Confirm |
para este comando. | |
No (N ): |
Não execute a ação. |
No to All (L ): |
Não execute nenhuma ação e suprima as seguintes ações Confirm |
consultas para este comando. | |
Suspend (S ): |
Pause o comando e crie uma sessão temporária. |
Help (? ) |
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 Confirm opção. O prompt de comando para a sessão aninhada tem dois conjuntos de caracteres 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 "sair" para encerrar o prompt aninhado e 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