about_Parameters_Default_Values
Aplica-se a: Windows PowerShell 3.0
TÓPICO
about_Parameters_Default_Values
DESCRIÇÃO BREVE
Descreve como definir valores padrão personalizados para os parâmetros de cmdlets e funções avançadas.
DESCRIÇÃO LONGA
A variável de preferência $PSDefaultParameterValues permite que você especifique valores padrão personalizados para qualquer cmdlet ou função avançada. Cmdlets e funções usam o valor padrão personalizado, a menos que você especifique outro valor no comando.
Os autores de cmdlets e funções avançadas definem valores padrão para os parâmetros. Normalmente, os valores padrão são úteis, mas podem não ser apropriados para todos os ambientes.
Esse recurso é especialmente útil quando você precisar especificar o mesmo valor de parâmetro alternativo quase sempre que usar o comando ou quando um valor de parâmetro específico for difícil de lembrar, como um nome de servidor de email ou o GUID do projeto.
Se o valor padrão desejado varia de maneira previsível, você pode especificar um bloco de script que fornece diferentes valores padrão para um parâmetro em condições diferentes.
$PSDefaultParameterValues foi introduzido no Windows PowerShell 3.0.
SINTAXE
A sintaxe da variável de preferência $PSDefaultParameterValues é a seguinte:
$PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"="<DefaultValue>"}
$PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"={<ScriptBlock>}}
$PSDefaultParameterValues["Disabled"]=$true | $false
Caracteres curinga são permitidos nos valores de CmdletName e ParameterName.
O valor de $PSDefaultParameterValues é um System.Management.Automation.DefaultParameterDictionary, um tipo de tabela de hash que valida o formato de chaves. Insira uma tabela de hash, na qual a chave consiste do nome do cmdlet e nome do parâmetro separados por dois-pontos (:) e o valor é o valor padrão personalizado.
Para definir, alterar, adicionar ou remover entradas de $PSDefaultParameterValues, use os métodos que você usaria para editar uma tabela de hash padrão.
O <CmdletName> deve ser o nome de um cmdlet ou o nome de uma função avançada que usa o atributo CmdletBinding. Você não pode usar $PSDefaultParameterValues para especificar valores padrão para scripts ou funções simples.
O valor padrão pode ser um objeto ou um bloco de script. Se o valor for um bloco de script, o Windows PowerShell avalia o bloco de script e usa o resultado como o valor do parâmetro. Quando o parâmetro especificado tem um valor de bloco de script, coloque o valor de bloco de script em um segundo conjunto de chaves, como: $PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }
Para obter informações sobre tabelas de hash, consulte about_Hash_Tables. Para obter informações sobre blocos de script, consulte about_Script_Blocks. Para obter informações sobre variáveis de preferências, consulte about_Preference_Variables.
EXEMPLOS
O comando a seguir define um valor padrão personalizado para o parâmetro SmtpServer do cmdlet Send-MailMessage.
$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"}
Para definir valores padrão para vários parâmetros, use um ponto e vírgula (;) para separar cada par Name=Value. O comando a seguir adiciona um valor padrão personalizado para o parâmetro LogName do cmdlet Get-WinEvent.
$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
"Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"}
Você pode usar caracteres curinga no nome do cmdlet e parâmetro. O comando a seguir define o parâmetro comum Verbose como $true em todos os comandos. Use $true e $false para definir valores para parâmetros de opção, como Verbose.
$PSDefaultParameterValues = @{"*:Verbose"=$true}
Se um parâmetro aceita vários valores (uma matriz), você pode definir vários valores como o valor padrão. O comando a seguir define o valor padrão do parâmetro ComputerName do cmdlet Invoke-Command "Server01" e "Server02".
$PSDefaultParameterValues = @{"Invoke-Command:ComputerName"="Server01","Server02"}
É possível usar um bloco de script para especificar valores padrão diferentes para um parâmetro sob condições diferentes. O Windows PowerShell avalia o bloco de script e usa o resultado como o valor de parâmetro padrão.
O comando a seguir define o valor padrão do parâmetro Autosize do cmdlet Format-Table como $true quando o programa do host é o console do Windows PowerShell.
$PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name –eq "ConsoleHost"){$true}}}
Se um parâmetro aceitar um valor de bloco de script, coloque o bloco de script em um conjunto extra de chaves. Quando Windows PowerShell avalia o bloco de script externo, o resultado é o bloco de script interno, que é definido como o valor de parâmetro padrão.
O comando a seguir define o valor padrão do parâmetro ScriptBlock de Invoke-Command. Como o bloco de script é colocado em um segundo conjunto de chaves, o bloco de script entre chaves é passado para o cmdlet Invoke-Command.
$PSDefaultParameterValues=@{"Invoke-Command:ScriptBlock"={{Get-EventLog –Log System}}}
COMO DEFINIR $PSDefaultParameterValues
$PSDefaultParameterValues é uma variável de preferência, então ela existe apenas na sessão na qual está definida. Ela não tem valor padrão.
Para definir $PSDefaultParameterValues, digite o nome da variável e um ou mais pares de chave-valor na linha de comando.
Se você digitar outro comando $PSDefaultParameterValues, seu valor substitui o valor original. O original não é mantido.
Para salvar $PSDefaultParameterValues para futuras sessões, adicione um comando $PSDefaultParameterValues no perfil do Windows PowerShell. Para obter mais informações, consulte about_Profiles.
COMO OBTER $PSDefaultParameterValues
Para obter o valor de $PSDefaultParameterValues, no prompt de comando, digite: $PSDefaultParameterValues
Por exemplo, o primeiro comando define o valor de $PSDefaultParameterValues. O segundo comando obtém o valor de $PSDefaultParameterValues.
PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
"Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational";
"Get-*:Verbose"=$true}
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
Para obter o valor de uma chave <CmdletName:ParameterName>, use a seguinte sintaxe de comando:
$PSDefaultParameterValues["<CmdletName:ParameterName>"]
Por exemplo:
PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
Server01AB234x5
COMO ADICIONAR VALORES A $PSDefaultParameterValues
Para adicionar ou remover valores de $PSDefaultParameterValues, use os métodos que você usaria para uma tabela de hash padrão.
Por exemplo, para adicionar um valor para $PSDefaultParameterValues sem afetar os valores existentes, use o método Add das tabelas de hash.
A sintaxe do método Add é da seguinte maneira:
<HashTable>.Add(Key, Value)
em que a chave é "<CmdletName>:<ParameterName>" e o valor é o valor do parâmetro.
Use o seguinte formato de comando para chamar o método Add no $PSDefaultParameterValues. Certifique-se de usar uma vírgula (,) para separar a chave do valor, em vez do sinal de igual (=).
$PSDefaultParameterValues.Add("<CmdletName>:<ParameterName>", "<ParameterValue>")
Por exemplo, o comando a seguir adiciona "PowerShell" como o valor padrão do parâmetro Name do cmdlet Get-Process.
$PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")
O exemplo a seguir mostra o efeito desse comando.
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Get-Process:Name PowerShell
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
COMO REMOVER VALORES DE $PSDefaultParameterValues
Para remover um valor de $PSDefaultParameterValues, use o método Remove das tabelas de hash.
A sintaxe do método Remove é da seguinte maneira:
<HashTable>.Remove(Key)
Use o seguinte formato de comando para chamar o método Remove no $PSDefaultParameterValues.
$PSDefaultParameterValues.Remove("<CmdletName>:<ParameterName>")
Por exemplo, o comando a seguir remove o parâmetro Name do cmdlet Get-Process e seus valores.
$PSDefaultParameterValues.Remove("Get-Process:Name")
O exemplo a seguir mostra o efeito desse comando.
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Get-Process:Name PowerShell
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name")
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
COMO ALTERAR OS VALORES EM $PSDefaultParameterValues
Para alterar um valor em $PSDefaultParameterValues, use o seguinte formato de comando.
$PSDefaultParameterValues["CmdletName:ParameterName"]="<NewValue>"
O exemplo a seguir mostra o efeito desse comando.
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5"
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server0000cabx5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
COMO DESABILITAR E REABILITAR $PSDefaultParameterValues
Você pode desabilitar temporariamente e, em seguida, reabilitar $PSDefaultParameterValues. Isso é muito útil se você estiver executando scripts que podem assumir valores de parâmetro padrão diferentes.
Para desabilitar $PSDefaultParameterValues, adicione uma chave de "Desabilitado" com um valor de $True.
Por exemplo,
$PSDefaultParameterValues.Add("Disabled", $true)
- or -
$PSDefaultParameterValues[Disabled]=$true
Os outros valores em $PSDefaultParameterValues são preservados, mas não são eficazes.
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Disabled True
Send-MailMessage:SmtpServer Server0000cabx5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
Para reabilitar $PSDefaultParameterValues, remova a chave Desabilitada ou altere o valor da chave de Desabilitada para $False.
$PSDefaultParameterValues.Remove("Disabled")
- or -
$PSDefaultParameterValues[Disabled]=$false
O valor anterior de $PSDefaultParameterValues é eficaz novamente.
PALAVRAS-CHAVE
about_PSDefaultParameterValues
about_Parameters_DefaultValues
about_DefaultValues
CONSULTE TAMBÉM
about_Hash_Tables
about_Preference_Variables
about_Profiles
about_Script_Blocks