about_Parameters_Default_Values
Descrição breve
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ê usa o comando
- especificando um valor de parâmetro específico que é difícil de lembrar, como um nome de servidor de email ou GUID de 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 é um hashtable com alguma validação extra para o formato das chaves. A tabela hash 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 (Get-Command -Name .\script.ps1).Name.
Nota
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 esperar um tipo de ScriptBlock, você deverá incluir o valor 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 de parâmetro padrão.
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 de $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'
Atribuir valores a $PSDefaultParameterValues
Para definir valores padrão para parâmetros de cmdlet, atribua um hashtable contendo os pares chave-valor apropriados à variável $PSDefaultParameterValues.
O 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 de cmdlet e parâmetro podem conter caracteres curinga. Use $true e $false para definir valores para parâmetros de alternância, como Detalhado. Este exemplo define o parâmetro comum 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 para uma matriz que contém os valores de cadeia de caracteres Server01 e Server02.
$PSDefaultParameterValues = @{
'Invoke-Command:ComputerName' = 'Server01','Server02'
}
Exibir 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
Use 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 diferentes condições. O PowerShell avalia o bloco de script e usa o resultado como o valor do parâmetro padrão.
A tecla Format-Table:AutoSize define esse parâmetro de alternância para um valor padrão de $true. A instrução if contém uma condição em que o $Host.Name deve ser ConsoleHost.
$PSDefaultParameterValues = @{
'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} }
}
Se um parâmetro aceitar um valor ScriptBlock, coloque o ScriptBlock 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 de parâmetro padrão.
$PSDefaultParameterValues = @{
'Invoke-Command:ScriptBlock' = { {Get-EventLog -Log System} }
}
Adicionar valores a uma variável de $PSDefaultParameterValues existente
Para adicionar um valor a $PSDefaultParameterValues, use o método Add(). Adicionar um valor não afeta os valores existentes do hashtable. Use uma vírgula (,) para separar a chave do valor .
$PSDefaultParameterValues.Add('Get-Process:Name', 'PowerShell')
O hashtable criado no exemplo anterior é atualizado 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 do 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 um valor em $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 da 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
Desabilitar ou habilitar novamente $PSDefaultParameterValues
Você pode desativar 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 $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 habilitar novamente $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
