about_Parameters_Default_Values

Aplica-se a: Windows PowerShell 3.0

TÓPICO

about_Parameters_Default_Values

DESCRIÇÃO BREVE

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

DESCRIÇÃO LONGA

A variável de preferência $PSDefaultParameterValues permite que você especifique valores padrão personalizados para qualquer cmdlet ou função avançada. Cmdlets e funções 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 os parâmetros. Normalmente, os valores padrão são úteis, mas podem não ser apropriados para todos os ambientes.

Esse recurso é especialmente útil quando você precisar especificar o mesmo valor de parâmetro alternativo quase sempre que usar o comando ou quando um valor de parâmetro específico for difícil de lembrar, como um nome de servidor de email ou o GUID do projeto.

Se o valor padrão desejado varia de maneira previsível, você pode especificar um bloco de script que fornece diferentes valores padrão para um parâmetro em condições diferentes.

$PSDefaultParameterValues foi introduzido no Windows PowerShell 3.0.

SINTAXE

A sintaxe da variável de preferência $PSDefaultParameterValues é a seguinte:

       $PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"="<DefaultValue>"}

       $PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"={<ScriptBlock>}}

       $PSDefaultParameterValues["Disabled"]=$true | $false

Caracteres curinga são permitidos nos valores de CmdletName e ParameterName.

O valor de $PSDefaultParameterValues é um System.Management.Automation.DefaultParameterDictionary, um tipo de tabela de hash que valida o formato de chaves. Insira uma tabela de hash, na qual a chave consiste do nome do cmdlet e nome do parâmetro separados por dois-pontos (:) e o valor é o valor padrão personalizado.

Para definir, alterar, adicionar ou remover entradas de $PSDefaultParameterValues, use os métodos que você usaria para editar uma tabela de hash padrão.

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 valor padrão pode ser um objeto ou um bloco de script. Se o valor for um bloco de script, o Windows PowerShell avalia o bloco de script e usa o resultado como o valor do parâmetro. Quando o parâmetro especificado tem um valor de bloco de script, coloque o valor de bloco de script em um segundo conjunto de chaves, como: $PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }

Para obter informações sobre tabelas de hash, consulte about_Hash_Tables. Para obter informações sobre blocos de script, consulte about_Script_Blocks. Para obter informações sobre variáveis de preferências, consulte about_Preference_Variables.

EXEMPLOS

O comando a seguir define um valor padrão personalizado para o parâmetro SmtpServer do cmdlet Send-MailMessage.

        $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"}

Para definir valores padrão para vários parâmetros, use um ponto e vírgula (;) para separar cada par Name=Value. O comando a seguir adiciona um valor padrão personalizado para o parâmetro LogName do cmdlet Get-WinEvent.

        $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
               "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"}

Você pode usar caracteres curinga no nome do cmdlet e parâmetro. O comando a seguir define o parâmetro comum Verbose como $true em todos os comandos. Use $true e $false para definir valores para parâmetros de opção, como Verbose.

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

Se um parâmetro aceita vários valores (uma matriz), você pode definir vários valores como o valor padrão. O comando a seguir define o valor padrão do parâmetro ComputerName do cmdlet Invoke-Command "Server01" e "Server02".

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

É possível usar um bloco de script para especificar valores padrão diferentes para um parâmetro sob condições diferentes. O Windows PowerShell avalia o bloco de script e usa o resultado como o valor de parâmetro padrão.

O comando a seguir define o valor padrão do parâmetro Autosize do cmdlet Format-Table como $true quando o programa do host é o console do Windows PowerShell.

        $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 Windows PowerShell avalia o bloco de script externo, o resultado é o bloco de script interno, que é definido como o valor de parâmetro padrão.

O comando a seguir define o valor padrão do parâmetro ScriptBlock de Invoke-Command. Como o bloco de script é colocado em um segundo conjunto de chaves, o bloco de script entre chaves é passado para o cmdlet Invoke-Command.

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

COMO DEFINIR $PSDefaultParameterValues

$PSDefaultParameterValues é uma variável de preferência, então ela existe apenas na sessão na qual está definida. Ela não tem valor padrão.

Para definir $PSDefaultParameterValues, digite o nome da variável e um ou mais pares de chave-valor na linha de comando.

Se você digitar outro comando $PSDefaultParameterValues, seu valor substitui o valor original. O original não é mantido.

Para salvar $PSDefaultParameterValues para futuras sessões, adicione um comando $PSDefaultParameterValues no perfil do Windows PowerShell. Para obter mais informações, consulte about_Profiles.

COMO OBTER $PSDefaultParameterValues

Para obter o valor de $PSDefaultParameterValues, no prompt de comando, digite: $PSDefaultParameterValues

Por exemplo, o primeiro comando define o valor de $PSDefaultParameterValues. O segundo comando obtém o valor de $PSDefaultParameterValues.

        PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
                "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational";
                "Get-*:Verbose"=$true}

        PS C:\> $PSDefaultParameterValues

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

Para obter o valor de uma chave <CmdletName:ParameterName>, use a seguinte sintaxe de comando:

       $PSDefaultParameterValues["<CmdletName:ParameterName>"]

Por exemplo:

       PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
       Server01AB234x5   

COMO ADICIONAR VALORES A $PSDefaultParameterValues

Para adicionar ou remover valores de $PSDefaultParameterValues, use os métodos que você usaria para uma tabela de hash padrão.

Por exemplo, para adicionar um valor para $PSDefaultParameterValues sem afetar os valores existentes, use o método Add das tabelas de hash.

A sintaxe do método Add é da seguinte maneira:

        <HashTable>.Add(Key, Value)

em que a chave é "<CmdletName>:<ParameterName>" e o valor é o valor do parâmetro.

Use o seguinte formato de comando para chamar o método Add no $PSDefaultParameterValues. Certifique-se de usar uma vírgula (,) para separar a chave do valor, em vez do sinal de igual (=).

        $PSDefaultParameterValues.Add("<CmdletName>:<ParameterName>", "<ParameterValue>")

Por exemplo, o comando a seguir adiciona "PowerShell" como o valor padrão do parâmetro Name do cmdlet Get-Process.

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

O exemplo a seguir mostra o efeito desse comando.

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")

        PS C:\> $PSDefaultParameterValues

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

COMO REMOVER VALORES DE $PSDefaultParameterValues

Para remover um valor de $PSDefaultParameterValues, use o método Remove das tabelas de hash.

A sintaxe do método Remove é da seguinte maneira:

        <HashTable>.Remove(Key)

Use o seguinte formato de comando para chamar o método Remove no $PSDefaultParameterValues.

        $PSDefaultParameterValues.Remove("<CmdletName>:<ParameterName>")

Por exemplo, o comando a seguir remove o parâmetro Name do cmdlet Get-Process e seus valores.

        $PSDefaultParameterValues.Remove("Get-Process:Name")

O exemplo a seguir mostra o efeito desse comando.

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name")

        PS C:\> $PSDefaultParameterValues

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

COMO ALTERAR OS VALORES EM $PSDefaultParameterValues

Para alterar um valor em $PSDefaultParameterValues, use o seguinte formato de comando.

        $PSDefaultParameterValues["CmdletName:ParameterName"]="<NewValue>"

O exemplo a seguir mostra o efeito desse comando.

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5"
   
        PS C:\> $PSDefaultParameterValues

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

COMO DESABILITAR E REABILITAR $PSDefaultParameterValues

Você pode desabilitar temporariamente e, em seguida, reabilitar $PSDefaultParameterValues. Isso é muito útil se você estiver executando scripts que podem assumir valores de parâmetro padrão diferentes.

Para desabilitar $PSDefaultParameterValues, adicione uma chave de "Desabilitado" com um valor de $True.

Por exemplo,

        $PSDefaultParameterValues.Add("Disabled", $true)

        - or -

        $PSDefaultParameterValues[Disabled]=$true

Os outros valores em $PSDefaultParameterValues são preservados, mas não são eficazes.

        PS C:\> $PSDefaultParameterValues

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

Para reabilitar $PSDefaultParameterValues, remova a chave Desabilitada ou altere o valor da chave de Desabilitada para $False.

        $PSDefaultParameterValues.Remove("Disabled")

- or -

        $PSDefaultParameterValues[Disabled]=$false

O valor anterior de $PSDefaultParameterValues é eficaz novamente.

PALAVRAS-CHAVE

about_PSDefaultParameterValues

about_Parameters_DefaultValues

about_DefaultValues

CONSULTE TAMBÉM

about_Hash_Tables

about_Preference_Variables

about_Profiles

about_Script_Blocks