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 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 toda vez que usa o comando ou quando um valor de parâmetro específico é difícil de lembrar, como um nome de servidor de email ou GUID do projeto.
Se o valor padrão desejado variar de forma previsível, você poderá especificar um bloco de script que fornece valores padrão diferentes para um parâmetro em condições diferentes.
$PSDefaultParameterValues
foi introduzido no PowerShell 3.0.
Syntax
A $PSDefaultParameterValues
variável é uma tabela de hash que valida o formato das 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 Valor é 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
, use os métodos para editar uma tabela de hash 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, portanto, ela existe somente na sessão em que está definida. Não tem nenhum valor padrão.
Para definir , digite $PSDefaultParameterValues
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
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 caracteres curinga e parâmetros de opção
Os nomes de cmdlet e parâmetro podem conter caracteres curinga. Use $True
e $False
para definir valores para parâmetros switch, como Verbose. O parâmetro Verbose do parâmetro comum é definido $True
como 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 de parâmetro padrão.
A Format-Table:AutoSize
chave define que alterna o parâmetro para um valor padrão de True. A If
instrução contém uma condição de que o $host.Name
deve 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 e é 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á entre chaves. O resultado do bloco de script é passado para o Invoke-Command
cmdlet .
$PSDefaultParameterValues=@{
"Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}
}
Como obter $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 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 a $PSDefaultParameterValues
Para adicionar um valor a $PSDefaultParameterValues
, use o método Add . Adicionar 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 realiza 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 de $PSDefaultParameterValues
Para remover um valor de $PSDefaultParameterValues
, use o método Remove de tabelas de hash. Remover um valor não afeta os valores existentes da tabela de hash.
A sintaxe a seguir mostra como usar o método Remove em $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 de tabela de 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 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 desabilitar e reabilitar $PSDefaultParameterValues
Você pode desabilitar temporariamente e habilitar $PSDefaultParameterValues
novamente .
Desabilitar $PSDefaultParameterValues
é útil se você estiver executando scripts que precisam de valores de parâmetro padrão diferentes.
Para desabilitar $PSDefaultParameterValues
, 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 realiza 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 reabilitar $PSDefaultParameterValues
, remova a chave Desabilitada ou altere o valor da chave Desabilitada para $False
. O valor anterior de $PSDefaultParameterValues
é efetivado novamente.
PS> $PSDefaultParameterValues.Remove("Disabled")
A sintaxe a seguir realiza 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 reabilitar $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