about_Parameters_Default_Values
Descrição breve
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 valor de parâmetro específico é difícil de lembrar, como um nome de servidor de email ou GUID de 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 sob condições diferentes.
$PSDefaultParameterValues foi introduzido no PowerShell 3.0.
Sintaxe
A $PSDefaultParameterValues variável é uma tabela de hash que valida o formato de chaves como um tipo de objeto de System.Management.Automation.DefaultParameterDictionary. A tabela de 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 do , use os métodos para editar uma tabela de $PSDefaultParameterValueshash padrão. Por exemplo, os métodos Add e Remove . Esses métodos não substituem outros valores na tabela de hash.
Há outra sintaxe que não substitui uma tabela de hash existente $PSDefaultParameterValues . 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 um dos seguintes documentos:
Exemplos
Como definir $PSDefaultParameterValues
$PSDefaultParameterValues é uma variável de preferência, por isso existe apenas na sessão em que está definida. Ele não tem valor padrão.
Para definir $PSDefaultParameterValues, digite o nome da variável e um ou mais pares Chave/Valor . Se você executar outro $PSDefaultParameterValues comando, ele substituirá a tabela de 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 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 de cmdlet e parâmetro 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 pode aceitar vários valores, uma matriz, você pode 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 sob condições diferentes. O PowerShell avalia o bloco de script e usa o resultado como o valor de parâmetro padrão.
A Format-Table:AutoSize chave define esse parâmetro de alternância para um valor padrão de True. A If instrução contém uma condição que deve $host.Name ser o 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, que é definido como o valor de 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 é 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 de hash são exibidos inserindo $PSDefaultParameterValues no prompt do PowerShell.
Uma $PSDefaultParameterValues tabela de hash é definida com três pares Chave/Valor .
Essa tabela de hash é usada nos exemplos a seguir que descrevem como adicionar, alterar e remover valores do $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 agregar valores ao $PSDefaultParameterValues
Para adicionar um valor ao $PSDefaultParameterValues, use o método Add . A adição de um valor não afeta os valores existentes da tabela de 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 de 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 obtém o mesmo resultado.
$PSDefaultParameterValues["Get-Process:Name"]="PowerShell"
A $PSDefaultParameterValues variável exibe a tabela de 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 do $PSDefaultParameterValues
Para remover um valor do $PSDefaultParameterValues, use o método Remove de tabelas de hash. A remoção de um valor não afeta os valores existentes da tabela de hash.
A sintaxe a seguir mostra como usar o método Remove no $PSDefaultParameterValues.
PS> $PSDefaultParameterValues.Remove("CmdletName:ParameterName")
Neste exemplo, a tabela de 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 $PSDefaultParameterValues variável exibe a tabela de 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 em um valor específico não afetam os valores da tabela de hash existente. Para alterar um par Chave/Valor específico no $PSDefaultParameterValues, use a seguinte sintaxe:
PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"
Neste exemplo, a tabela de 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 $PSDefaultParameterValues variável exibe a tabela de 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 desabilitar temporariamente e reativar $PSDefaultParameterValueso .
A desativação $PSDefaultParameterValues é útil se você estiver executando scripts que precisam de valores de parâmetro padrão diferentes.
Para desabilitar $PSDefaultParameterValueso , adicione uma chave de Disabled com um valor True. Os valores em $PSDefaultParameterValues são preservados, mas não são eficazes.
PS> $PSDefaultParameterValues.Add("Disabled", $True)
A sintaxe a seguir obtém o mesmo resultado.
PS> $PSDefaultParameterValues["Disabled"]=$True
A $PSDefaultParameterValues variável exibe a tabela de hash atualizada com o valor da Disabled chave.
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 Disabled ou altere o valor da chave Disabled para $False. O valor anterior de $PSDefaultParameterValues é efetivo novamente.
PS> $PSDefaultParameterValues.Remove("Disabled")
A sintaxe a seguir obtém o mesmo resultado.
PS> $PSDefaultParameterValues["Disabled"]=$False
A $PSDefaultParameterValues variável exibe a tabela de 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 será exibida como False.
PS> $PSDefaultParameterValues
Name Value
---- -----
Disabled False
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de