about_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 Verbose parâmetro comum 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 .
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.
Para mais informações, consulte about_Preference_Variables.
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)
- AvisoVariável (wv)
Os parâmetros action são valores do tipo ActionPreference . ActionPreference é uma enumeração com os seguintes valores:
| Name | Valor |
|---|---|
Break |
6 |
Suspend |
5 |
Ignore |
4 |
Inquire |
3 |
Continue |
2 |
Stop |
1 |
SilentlyContinue |
0 |
Pode utilizar o nome ou o valor com o parâmetro.
Além dos parâmetros comuns, muitos cmdlets oferecem parâmetros de mitigação de riscos. Os cmdlets que envolvem risco para o sistema ou para os dados do utilizador geralmente oferecem estes parâmetros.
Os parâmetros de mitigação do risco são:
- WhatIf (wi)
- Confirm (cf)
Descrições comuns dos parâmetros
-Debug
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.
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 apresentadas porque o $DebugPreference valor da variável é SilentlyContinue.
Em modo interativo, o Debug parâmetro sobrepõe-se ao valor da $DebugPreference variável para o comando atual, definindo o valor de $DebugPreference inquirir.
No modo não interativo, o Debug parâmetro sobrepõe-se ao valor da $DebugPreference variável para o comando atual, definindo o valor de $DebugPreference Continuar.
-Debug:$true tem o mesmo efeito que -Debug. . Utilize -Debug:$false para suprimir a visualização de mensagens de depuração quando $DebugPreference não é SilentlyContinue, que é o padrão.
-ErrorAction
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.
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 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:Break Entra no depurar quando ocorre um erro ou se levanta uma exceção.
-ErrorAction:Continue exibe a mensagem de erro e continua a executar o comando. Continue é a predefinição.
-ErrorAction:Ignore suprime 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:Inquire exibe a mensagem de erro e solicita-lhe 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 deixa de executar o comando.
-ErrorAction:Suspend só está disponível para fluxos de trabalho que não são suportados no PowerShell 6 e mais além.
Nota
O parâmetro ErrorAction substitui, mas não substitui o valor da $ErrorActionPreference variável quando o parâmetro é utilizado num comando para executar um script ou função.
-ErroVariável
ErrorVariable armazena mensagens de erro sobre o comando na variável especificada e na $Error variável automática. Para mais informações, consulte about_Automatic_Variables
Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
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, 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 erros nele:
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 de $a:
$a
Pode utilizar este 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 da sessão. Pode utilizar a notação de matriz, como $a[0] ou $error[1,2] para se referir a erros específicos armazenados nas variáveis.
Nota
A variável de erro personalizado 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 em que é usado, o parâmetro comum InformationAction sobrepõe-se ao valor da $InformationPreference variável de preferência, que por padrão é definida para SilentlyContinue. Quando utiliza Write-Information num script com InformationAction, Write-Information os valores são apresentados dependendo do valor do parâmetro InformationAction . Para 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 Entra o depurador numa ocorrência do Write-Information comando.
-InformationAction:Stop para um comando ou script numa ocorrência do Write-Information comando.
-InformationAction:Ignore suprime 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:Inquire exibe a mensagem informativa que especifica num comando e, em Write-Information seguida, pergunta se pretende continuar.
-InformationAction:Continue exibe a mensagem informativa e continua a funcionar.
-InformationAction:Suspend não é suportado no PowerShell 6 e superior, uma vez que só está disponível para fluxos de trabalho.
-InformationAction:SilentlyContinue nenhum efeito, uma vez que a mensagem informativa não é exibida (Predefinição) e o script continua sem interrupção.
Nota
O parâmetro InformationAction substitui, mas não substitui o valor da $InformationAction variável de preferência quando o parâmetro é usado num comando para executar um script ou função.
-Informação Variavel
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-Information os 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 sobre $InformationPreference, consulte about_Preference_Variables.
Nota
A variável de informação contém todas as mensagens de informação geradas pelo comando, incluindo mensagens de informação 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 acumular-se num tampão antes de quaisquer objetos serem enviados através da tubagem. Se omitir este parâmetro, os objetos sã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
Este parâmetro de gestão de recursos foi concebido para utilizadores avançados. Quando utilizar 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
Armazena objetos de saída do comando na variável especificada, além de enviar a saída ao longo do oleoduto.
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 ser armazenada lá, digite um sinal 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
Nota
A variável criada pelo parâmetro OutVariable é um [System.Collections.ArrayList].
-PipelineVariable
PipelineVariable permite o acesso ao valor mais recente passado para o segmento seguinte do pipeline pelo comando que utiliza este parâmetro. Qualquer comando no oleoduto pode aceder ao valor utilizando o chamado PipelineVariable. O valor é atribuído à variável quando é passado para o segmento seguinte do pipeline. Isto torna o PipelineVariable mais fácil de usar do que uma variável temporária específica, que pode ter de ser atribuída em vários locais.
Ao contrário $_ ou $PSItem, a utilização de um PipelineVariable permite que qualquer comando de gasoduto aceda aos valores do gasoduto passados (e guardados) por comandos que não o comando imediatamente anterior. Os comandos do pipeline podem aceder ao último valor canalizado durante o processamento do próximo item que passa pelo oleoduto. Isto permite que um comando rermente a sua saída para um comando anterior (ou a si mesmo).
Nota
As funções avançadas podem ter até três blocos de script: begin, processe end. Ao utilizar o parâmetro PipelineVariable com funções avançadas, apenas os valores do primeiro bloco de script definido são atribuídos à variável à medida que a função funciona. Para mais informações, consulte as funções Avançadas. PowerShell 7.2 corrige este comportamento.
Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Valores válidos são cordas, o mesmo que para qualquer nome variável.
Atenção
O PipelineVariable é abrangido pelo gasoduto em que é invocado. As variáveis fora da tubagem, que utilizam o mesmo nome, são removidas antes da execução do gasoduto. O PipelineVariable fica fora de alcance quando o gasoduto termina. Se vários comandos dentro do pipeline especificarem o mesmo PipelineVariable , então existe apenas uma variável partilhada. Esta variável é atualizada com a mais recente saída canalizada do comando que especifica a variável.
Alguns comandos de bloqueio recolhem todos os itens do gasoduto antes de produzir qualquer saída, por exemplo Sort-Object ou Select-Object -Last. Qualquer PipelineVariable atribuído num comando antes de tal comando de bloqueio contém sempre o item entubado final do comando anterior quando utilizado num comando após o comando de bloqueio.
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 5, são canalizados para o primeiro Foreach-Object comando, dos quais os resultados são armazenados numa variável denominada $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
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 verbosa. Por exemplo, este 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 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:$true tem o mesmo efeito que -Verbose
-Verbose:$false suprime a exibição de mensagens verbosas. Utilize este parâmetro quando o valor de $VerbosePreference não é SilentlyContinue (o padrão).
-AdvertênciaAcção
Determina como o cmdlet responde a um aviso do comando. Continuar é o valor predefinido. 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.
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 sobrepõe-se ao valor da $WarningPreference variável para o comando atual. Como o valor predefinido da $WarningPreference variável é Continuar, os avisos são apresentados e a execução continua a menos que utilize o parâmetro WarningAction .
-WarningAction:Break entra no depurar quando ocorre um aviso.
-WarningAction:Continue exibe as mensagens de aviso e continua a executar o comando. Continue é a predefinição.
-WarningAction:Inquire exibe a mensagem de aviso e solicita-lhe 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.
Nota
O parâmetro WarningAction substitui, mas não substitui o valor da $WarningAction variável de preferência quando o parâmetro é utilizado num comando para executar um script ou função.
-AvisoVariável
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 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 lá armazenados, 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 de $a:
$a
Pode utilizar este parâmetro para criar uma variável que contém apenas avisos de comandos específicos. Pode utilizar a notação de matriz, como $a[0] ou $warning[1,2] para se referir a avisos específicos armazenados na variável.
Nota
A variável de aviso contém todas as advertências geradas pelo comando, incluindo avisos de chamadas para funções aninhadas ou scripts.
Descrições dos parâmetros de gestão de risco
- O QueIf
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 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, consulte 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 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".
-Confirm
Solicita-lhe 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 sobrepõe-se ao valor da $ConfirmPreference variável para o comando atual. O valor predefinido é true. Para 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 é inferior ou igual ao risco estimado do cmdlet.
Por exemplo, o seguinte comando utiliza o Confirm parâmetro 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 Confirm opções de resposta são as seguintes:
| Resposta | Resultado |
|---|---|
Yes (Y) |
Execute a ação. |
Yes to All (A) |
Realizar 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 realize quaisquer ações e suprima posteriormente Confirm |
| consultas para este comando. | |
Suspend (S): |
Faça uma pausa no comando e crie uma sessão temporária. |
Help (?) |
Mostrar ajuda para estas opções. |
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 Confirm opção. O pedido de comando para a sessão aninhada tem duas caretas extra (>>) para indicar que é uma operação infantil do comando dos pais originais. Pode executar comandos e scripts na sessão aninhada. Para terminar a sessão aninhada e voltar às Confirm opções 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) à 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
Ver também
Comentários
Submeter e ver comentários