about_Parameters_Default_Values
Breve descrição
Descreve como definir valores padrão personalizados para parâmetros de cmdlet e funções avançadas.
Descrição longa
A $PSDefaultParameterValues
variável de preferência permite especificar valores padrão personalizados para qualquer cmdlet ou função avançada. Cmdlets e funções avançadas 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 padrão para seus parâmetros. Normalmente, os valores padrão padrão são úteis, mas podem não ser apropriados para todos os ambientes.
Esse recurso é especialmente útil quando você deve especificar o mesmo valor de parâmetro alternativo quase sempre que usar o comando ou quando um determinado valor de parâmetro é difícil de lembrar, como um nome de servidor de email ou GUID do projeto.
Se o valor padrão desejado variar previsivelmente, você poderá especificar um bloco de script que forneça valores padrão diferentes para um parâmetro em condições diferentes.
$PSDefaultParameterValues
foi introduzido no PowerShell 3.0.
Sintaxe
A variável $PSDefaultParameterValues
é uma tabela hash que valida o formato das chaves como tipo de objeto System.Management.Automation.DefaultParameterDictionary. A tabela hash contém pares Chave/Valor. Uma chave está no formato CmdletName:ParameterName
. Um Value é o DefaultValue ou ScriptBlock atribuído à chave.
A sintaxe da variável de preferência é a $PSDefaultParameterValues
seguinte:
$PSDefaultParameterValues=@{"CmdletName:ParameterName"="DefaultValue"}
$PSDefaultParameterValues=@{ "CmdletName:ParameterName"={{ScriptBlock}} }
$PSDefaultParameterValues["Disabled"]=$True | $False
Caracteres curinga são permitidos nos valores CmdletName e ParameterName .
Para definir, alterar, adicionar ou remover um par Chave/Valor específico de $PSDefaultParameterValues
, utilize os métodos para editar uma tabela hash padrão. Por exemplo, os métodos Add e Remover . Estes métodos não substituem outros valores na tabela hash.
Existe outra sintaxe que não substitui uma tabela hash $PSDefaultParameterValues
existente. Para adicionar ou alterar um par chave/valor específico, use a seguinte sintaxe:
$PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"
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 DefaultValue pode ser um objeto ou um bloco de script. Se o valor for um bloco de script, o PowerShell avaliará o bloco de script e usará o resultado como o valor do parâmetro. Quando o parâmetro especificado aceitar um valor de bloco de script, coloque o valor do bloco de script em um segundo conjunto de chaves, como:
$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }
Para obter mais informações, consulte os documentos seguintes:
Exemplos
Como configurar $PSDefaultParameterValues
$PSDefaultParameterValues
é uma variável de preferência, por isso existe apenas na sessão em que está definida. Não tem valor padrão.
Para definir $PSDefaultParameterValues
, digite o nome da variável e um ou mais pares Chave/Valor . Se executar outro comando $PSDefaultParameterValues
, este substitui a tabela hash existente.
Para obter exemplos sobre como alterar pares Chave/Valor sem substituir valores de tabela de hash existentes, consulte Como adicionar valores a $PSDefaultParameterValues ou Como alterar valores em $PSDefaultParameterValues.
Para salvar $PSDefaultParameterValues
para sessões futuras, adicione um $PSDefaultParameterValues
comando ao seu perfil do PowerShell. Para obter mais informações, consulte about_Profiles.
Definir um valor padrão personalizado
O par Chave/Valor define a Send-MailMessage:SmtpServer
chave como um valor padrão personalizado de Server123.
$PSDefaultParameterValues = @{
"Send-MailMessage:SmtpServer"="Server123"
}
Definir valores padrão para vários parâmetros
Para definir valores padrão para vários parâmetros, separe cada par Chave/Valor com um ponto-e-vírgula (;
). As Send-MailMessage:SmtpServer
chaves e Get-WinEvent:LogName
são definidas como valores padrão personalizados.
$PSDefaultParameterValues = @{
"Send-MailMessage:SmtpServer"="Server123";
"Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"
}
Usar curingas e alternar parâmetros
Os nomes do cmdlet e dos parâmetros podem conter caracteres curinga. Use $True
e $False
defina valores para parâmetros de switch, como Verbose. O parâmetro Verbose do parâmetro comum é definido como $True
para todos os comandos.
$PSDefaultParameterValues = @{"*:Verbose"=$True}
Usar uma matriz para o valor padrão
Se um parâmetro puder aceitar vários valores, uma matriz, você poderá definir vários valores como os valores padrão. O valor padrão da Invoke-Command:ComputerName
chave é definido como um valor de matriz de Server01 e Server02.
$PSDefaultParameterValues = @{
"Invoke-Command:ComputerName"="Server01","Server02"
}
Usar um bloco de script
Você pode usar um bloco de script para especificar valores padrão diferentes para um parâmetro em condições diferentes. O PowerShell avalia o bloco de script e usa o resultado como o valor do parâmetro padrão.
A Format-Table:AutoSize
chave define esse parâmetro switch para um valor padrão de True. A If
instrução contém uma condição de que o deve ser o $host.Name
console do PowerShell, ConsoleHost.
$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 o PowerShell avalia o bloco de script externo, o resultado é o bloco de script interno, definido como o valor do parâmetro padrão.
A Invoke-Command:ScriptBlock
chave definida como um valor padrão do log de eventos do sistema porque o bloco de script está incluído em um segundo conjunto de chaves. O resultado do bloco de script é passado para o Invoke-Command
cmdlet.
$PSDefaultParameterValues=@{
"Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}
}
Como chegar $PSDefaultParameterValues
Os valores da tabela hash são apresentados ao introduzir $PSDefaultParameterValues
no pedido do PowerShell.
Uma tabela hash $PSDefaultParameterValues
é definida com três pares Chave/Valor.
Esta tabela hash é utilizada nos seguintes exemplos que descrevem como adicionar, alterar e remover valores de $PSDefaultParameterValues
.
PS> $PSDefaultParameterValues = @{
"Send-MailMessage:SmtpServer"="Server123"
"Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"
"Get-*:Verbose"=$True
}
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer Server123
Para obter o valor de uma chave específica CmdletName:ParameterName
, use a seguinte sintaxe:
$PSDefaultParameterValues["CmdletName:ParameterName"]
Por exemplo, para obter o valor da Send-MailMessage:SmtpServer
chave.
PS> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
Server123
Como adicionar valores ao $PSDefaultParameterValues
Para adicionar um valor ao $PSDefaultParameterValues
, use o método Add . Adicionar um valor não afeta os valores existentes da tabela hash.
Use uma vírgula (,
) para separar a chave do valor. A sintaxe a seguir mostra como usar o método Add para $PSDefaultParameterValues
.
PS> $PSDefaultParameterValues.Add("CmdletName:ParameterName", "DefaultValue")
A tabela hash criada no exemplo anterior é atualizada com um novo par Chave/Valor. O método Add define a Get-Process:Name
chave para o valor PowerShell.
$PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")
A sintaxe a seguir alcança o mesmo resultado.
$PSDefaultParameterValues["Get-Process:Name"]="PowerShell"
A variável $PSDefaultParameterValues
apresenta a tabela hash atualizada. A Get-Process:Name
chave foi adicionada.
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-Process:Name PowerShell
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer Server123
Como remover valores de $PSDefaultParameterValues
Para remover um valor de $PSDefaultParameterValues
, utilize o método Remove das tabelas hash. Remover um valor não afeta os valores existentes da tabela hash.
A sintaxe a seguir mostra como usar o método Remove no $PSDefaultParameterValues
.
PS> $PSDefaultParameterValues.Remove("CmdletName:ParameterName")
Neste exemplo, a tabela hash criada no exemplo anterior é atualizada para remover um par Chave/Valor. O método Remove remove a Get-Process:Name
chave.
$PSDefaultParameterValues.Remove("Get-Process:Name")
A variável $PSDefaultParameterValues
apresenta a tabela hash atualizada. A Get-Process:Name
chave foi removida.
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer Server123
Como alterar valores no $PSDefaultParameterValues
As alterações a um valor específico não afetam os valores da tabela hash existentes. Para alterar um par chave/valor específico no $PSDefaultParameterValues
, use a seguinte sintaxe:
PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"
Neste exemplo, a tabela hash criada no exemplo anterior é atualizada para alterar um par Chave/Valor. O comando a seguir altera a Send-MailMessage:SmtpServer
chave para um novo valor de ServerXYZ.
$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="ServerXYZ"
A variável $PSDefaultParameterValues
apresenta a tabela hash atualizada. A Send-MailMessage:SmtpServer
chave foi alterada para um novo valor.
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ
Como desativar e reativar $PSDefaultParameterValues
Você pode desativar temporariamente e, em seguida, reativar $PSDefaultParameterValues
o .
A desativação $PSDefaultParameterValues
é útil se você estiver executando scripts que precisam de valores de parâmetro padrão diferentes.
Para desativar $PSDefaultParameterValues
o , adicione uma chave de Disabled
com um valor True. Os valores são $PSDefaultParameterValues
preservados, mas não são eficazes.
PS> $PSDefaultParameterValues.Add("Disabled", $True)
A sintaxe a seguir alcança o mesmo resultado.
PS> $PSDefaultParameterValues["Disabled"]=$True
A variável $PSDefaultParameterValues
apresenta a tabela hash atualizada com o valor da chave Disabled
.
PS> $PSDefaultParameterValues
Name Value
---- -----
Disabled True
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ
Para reativar $PSDefaultParameterValues
, remova a chave Desabilitadoou altere o valor da chave Desabilitado para $False
. O valor anterior de $PSDefaultParameterValues
é efetivo novamente.
PS> $PSDefaultParameterValues.Remove("Disabled")
A sintaxe a seguir alcança o mesmo resultado.
PS> $PSDefaultParameterValues["Disabled"]=$False
A variável $PSDefaultParameterValues
apresenta a tabela hash atualizada. Quando o método Remove é usado, a Disabled
chave é removida da saída.
Se a sintaxe alternativa foi usada para reativar $PSDefaultParameterValues
, a Disabled
chave é exibida como False.
PS> $PSDefaultParameterValues
Name Value
---- -----
Disabled False
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ