Partilhar via

about_Parameters_Default_Values

  • Artigo

Breve descrição

Descreve como definir valores padrão personalizados para parâmetros de cmdlet, funções avançadas e scripts.

Descrição longa

A variável de preferência $PSDefaultParameterValues permite especificar valores de parâmetro padrão personalizados para qualquer cmdlet, função avançada ou script que use o atributo CmdletBinding. Os valores definidos são usados, a menos que você especifique outros valores na linha de comando.

Esse recurso é útil nos seguintes cenários:

  • especificando o mesmo valor de parâmetro sempre que você usar o comando
  • especificando um valor de parâmetro específico que é difícil de lembrar, como um nome de servidor de e-mail ou GUID do projeto

A variável $PSDefaultParameterValues não tem valor padrão. Para salvar as configurações para uso em sessões futuras, adicione a atribuição de variável ao seu perfil do PowerShell.

$PSDefaultParameterValues foi introduzido no PowerShell 3.0.

Sintaxe

A variável $PSDefaultParameterValues é um tipo de objeto de System.Management.Automation.DefaultParameterDictionary. O tipo DefaultParameterDictionary é uma hashtable com validação adicional para o formato das chaves. A hashtable contém pares chave-valor onde:

  • A chave tem o formato CommandName:ParameterName
  • o valor é o valor padrão para o parâmetro ou um ScriptBlock que retorna o valor padrão

Para a chave , o CommandName deve ser o nome de um cmdlet, função avançada ou arquivo de script que usa o atributo CmdletBinding. O nome do script deve corresponder ao nome tal como relatado pelo (Get-Command -Name .\script.ps1).Name.

Observação

O PowerShell não impede que você especifique um alias para o CommandName. No entanto, há casos em que a definição é ignorada ou causa um erro. Você deve evitar definir valores padrão para aliases de comando.

O valor pode ser um objeto de um tipo compatível com o parâmetro ou um ScriptBlock que retorna esse valor. Quando o valor é um bloco de script, o PowerShell avalia o bloco de script e usa o resultado para o valor do parâmetro. Se o parâmetro especificado espera um tipo de ScriptBlock, o valor deve ser colocado em outro conjunto de chaves. Quando o PowerShell avalia o ScriptBlock externo , o resultado é o ScriptBlock interno . O ScriptBlock interno torna-se o novo valor predefinido do parâmetro.

Por exemplo:

$PSDefaultParameterValues = @{
    'Invoke-Command:ScriptBlock' = { {Get-Process} }
}

Exemplos

Use os métodos Add() e Remove() para adicionar ou remover um par chave-valor específico do $PSDefaultParameterValues sem substituir outros pares chave-valor existentes.

$PSDefaultParameterValues.Add('CmdletName:ParameterName', 'DefaultValue')
$PSDefaultParameterValues.Remove('CmdletName:ParameterName')

Use a indexação ou o acesso de membro para alterar o valor de um par chave-valor existente. Por exemplo:

$PSDefaultParameterValues.'CommandName:ParameterName'='DefaultValue2'
$PSDefaultParameterValues['CommandName:ParameterName']='DefaultValue1'

Atribua valores a $PSDefaultParameterValues

Para definir valores padrão para parâmetros de cmdlet, atribua uma hashtable contendo os pares chave-valor apropriados à variável $PSDefaultParameterValues. A hashtable pode conter vários pares chave-valor. Este exemplo define valores padrão para as chaves Send-MailMessage:SmtpServer e Get-WinEvent:LogName.

$PSDefaultParameterValues = @{
  'Send-MailMessage:SmtpServer'='Server123'
  'Get-WinEvent:LogName'='Microsoft-Windows-PrintService/Operational'
}

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. Este exemplo define o parâmetro comum Verbose como $true para todos os comandos.

$PSDefaultParameterValues = @{'*:Verbose'=$true}

Se um parâmetro aceitar vários valores, você poderá fornecer vários valores padrão usando uma matriz. Este exemplo define o valor padrão da chave Invoke-Command:ComputerName como uma matriz que contém os valores de cadeia de caracteres Server01 e Server02.

$PSDefaultParameterValues = @{
  'Invoke-Command:ComputerName' = 'Server01', 'Server02'
}

Ver valores definidos

Considere a seguinte definição de $PSDefaultParameterValues:

$PSDefaultParameterValues = @{
  'Send-MailMessage:SmtpServer' = 'Server123'
  'Get-WinEvent:LogName' = 'Microsoft-Windows-PrintService/Operational'
  'Get-*:Verbose' = $true
}

Você pode exibir os valores definidos inserindo $PSDefaultParameterValues no prompt de comando.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Você pode usar a indexação ou o acesso de membro para obter um valor específico.

PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer'] # index notation
Server123
PS> $PSDefaultParameterValues.'Get-*:Verbose' # member access notation
True

Utilize um bloco de script para o valor padrão

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 chave Format-Table:AutoSize define esse parâmetro switch para um valor padrão de $true A instrução if contém uma condição de que o $Host.Name deve ser ConsoleHost.

$PSDefaultParameterValues = @{
  'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} }
}

Se um parâmetro aceitar um valor de ScriptBlock, coloque o ScriptBlock em outro conjunto de chaves. Quando o PowerShell avalia oexterno ScriptBlock , o resultado é o interno ScriptBlock. O ScriptBlock interno torna-se o novo valor de parâmetro padrão.

$PSDefaultParameterValues = @{
  'Invoke-Command:ScriptBlock' = { {Get-EventLog -Log System} }
}

Adicionar valores a uma variável $PSDefaultParameterValues existente

Para adicionar um valor a $PSDefaultParameterValues, use o método Add(). Adicionar um valor não afeta os valores existentes da hashtable. Use uma vírgula (,) para separar a chave do valor .

$PSDefaultParameterValues.Add('Get-Process:Name', 'PowerShell')

A hashtable criada no exemplo anterior é atualizada com um novo par chave-valor.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-Process:Name               PowerShell
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Remover um valor de $PSDefaultParameterValues

Para remover um valor de $PSDefaultParameterValues, use o método Remove(). A remoção de um valor não afeta os valores existentes da hashtable.

Este exemplo remove o par chave-valor que foi adicionado no exemplo anterior.

PS> $PSDefaultParameterValues.Remove('Get-Process:Name')
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Alterar o valor no $PSDefaultParameterValues

Use a indexação ou o acesso de membro para alterar o valor padrão de um par chave-valor existente. Neste exemplo, o valor padrão para a chave Send-MailMessage:SmtpServer é alterado para um novo valor de ServerXYZ.

PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer']='ServerXYZ'
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

Desativar ou 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 $PSDefaultParameterValues, adicione uma chave de Disabled com um valor de $true. Os valores em $PSDefaultParameterValues são preservados, mas não são usados.

PS> $PSDefaultParameterValues.Add('Disabled', $true)
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.

PS> $PSDefaultParameterValues.Disabled = $false
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Disabled                       False
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

Consulte também