Partilhar via

about_Parameters_Default_Values

  • Artigo

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 $PSDefaultParameterValueso . A desativação $PSDefaultParameterValues é útil se você estiver executando scripts que precisam de valores de parâmetro padrão diferentes.

Para desativar $PSDefaultParameterValueso , 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

Consulte também