about_Functions_Advanced_Parameters

Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

TÓPICO

Insira o corpo da seção aqui.

DESCRIÇÃO BREVE

Explica como adicionar parâmetros a funções avançadas.

DESCRIÇÃO LONGA

Você pode adicionar parâmetros às funções avançadas que você escreve e pode usar atributos de parâmetro e argumentos para limitar os valores de parâmetro que os usuários de função enviam com o parâmetro.

Os parâmetros que você adiciona à sua função estão disponíveis para usuários, além dos parâmetros comuns que o Windows PowerShell® adiciona automaticamente a todos os cmdlets e funções avançadas. Para obter mais informações sobre os parâmetros comuns do Windows PowerShell, consulte about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

A partir de Windows PowerShell 3.0, você pode usar nivelamento com @Args para representar os parâmetros em um comando. Essa técnica é válida em funções simples e avançadas. Para obter mais informações, consulte about_Functions (https://go.microsoft.com/fwlink/?LinkID=113231) e about_Splatting (https://go.microsoft.com/fwlink/?LinkID=262720).

PARÂMETROS ESTÁTICOS

Parâmetros estáticos são parâmetros que estão sempre disponíveis na função. A maioria dos parâmetros em cmdlets e scripts do Windows PowerShell são parâmetros estáticos.

O exemplo a seguir mostra a declaração de um parâmetro ComputerName que tem as seguintes características:

É obrigatório (fundamental).

Ele usa a entrada do pipeline.

Ele usa uma matriz de cadeias de caracteres como entrada.

        Param
          (
            [parameter(Mandatory=$true,
            ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          )

ATRIBUTOS DE PARÂMETROS

Esta seção descreve os atributos que você pode adicionar aos parâmetros de função.

Todos os atributos são opcionais. No entanto, se você omitir o atributo CmdletBinding, para ser reconhecida como uma função avançada, a função deve incluir o atributo de parâmetro.

Você pode adicionar um ou vários atributos em cada declaração de parâmetro. Não há nenhum limite para o número de atributos que podem ser adicionados a uma declaração de parâmetro.

O ATRIBUTO DE PARÂMETRO

O atributo de parâmetro é usado para declarar os atributos dos parâmetros da função.

O atributo de parâmetro é opcional e você pode omiti-lo se nenhum dos parâmetros de suas funções precisar de atributos, mas para ser reconhecida como uma função avançada (em vez de uma função simples), uma função deve ter o atributo CmdletBinding ou o atributo de parâmetro ou ambos.

O atributo de parâmetro tem argumentos que definem as características do parâmetro, como se o parâmetro é obrigatório ou opcional.

Use a seguinte sintaxe para declarar o atributo de parâmetro, um argumento e um valor de argumento. Os parênteses que incluem o argumento e seu valor devem seguir "Parâmetro" sem espaço intermediário.

        Param
          (
            [parameter(Argument=value)]
            $ParameterName
          )

Use vírgulas para separar os argumentos entre parênteses. Use a seguinte sintaxe para declarar dois argumentos do atributo de parâmetro.

        Param
          (
            [parameter(Argument1=value1,
                       Argument2=value2)]

          )

Se você usar o atributo de parâmetro sem argumentos (como uma alternativa ao uso do atributo CmdletBinding), os parênteses que seguem o nome do atributo ainda serão necessários.

        Param
          (
            [parameter()]
            $ParameterName
          )

Argumento obrigatório

O argumento obrigatório indica que o parâmetro é necessário. Se esse argumento não for especificado, o parâmetro será um parâmetro opcional.

O exemplo a seguir declara o parâmetro ComputerName. Ele usa o argumento obrigatório para tornar o parâmetro obrigatório.

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            $ComputerName
          )

Argumento de posição

O argumento de posição determina se o nome do parâmetro é necessário quando o parâmetro é usado em um comando. Quando uma declaração de parâmetro inclui o argumento de posição, o nome do parâmetro pode ser omitido e Windows PowerShell identifica o valor do parâmetro sem nome por sua posição (ou ordem) na lista de valores de parâmetro sem nome no comando.

Se o argumento de posição não for especificado, o nome do parâmetro (ou um alias do nome do parâmetro ou abreviação) deve preceder o valor do parâmetro sempre que o parâmetro for usado em um comando.

Por padrão, todos os parâmetros de função são posicionais. O Windows PowerShell alinha os números da posição aos parâmetros na ordem em que eles foram declarados na função. Para desabilitar esse recurso, defina o valor do argumento PositionalBinding do atributo CmdletBinding como $False. O argumento de posição tem precedência sobre o valor do argumento PositionalBinding para os parâmetros nos quais é declarado. Para obter mais informações, consulte PositionalBinding em about_Functions_CmdletBindingAttribute.

O valor do argumento de posição é especificado como um inteiro. Um valor de posição 0 representa a primeira posição no comando, um valor de posição de 1 representa a segunda posição no comando e assim por diante.

Se uma função não tiver parâmetros posicionais, o Windows PowerShell atribui posições para cada parâmetro com base na ordem em que os parâmetros são declarados. No entanto, como uma prática recomendada, não confie nessa atribuição. Quando você quiser que os parâmetros sejam posicionais, use o argumento de posição.

O exemplo a seguir declara o parâmetro ComputerName. Ele usa o argumento de posição com um valor de 0. Como resultado, quando "-ComputerName" for omitido do comando, seu valor deverá ser o primeiro ou o único valor de parâmetro no comando sem nome.

        Param
          (
            [parameter(Position=0)]
            [String[]]
            $ComputerName
          )

OBSERVAÇÃO:

Quando o cmdlet Get-Help exibe o atributo correspondente do parâmetro "Posição?", o valor da posição é incrementado em 1. Por exemplo, um parâmetro com um valor de argumento de posição 0 tem um atributo de parâmetro de "Position? 1."

Argumento ParameterSetName

O argumento ParameterSetName especifica o conjunto de parâmetros ao qual um parâmetro pertence. Se nenhum conjunto de parâmetro for especificado, o parâmetro pertence a todos os conjuntos de parâmetro definidos pela função. Portanto, para ser exclusivo, cada conjunto de parâmetros deve ter pelo menos um parâmetro que não seja um membro de qualquer outro conjunto de parâmetro.

O exemplo a seguir declara um parâmetro ComputerName no conjunto de parâmetros de computador, um parâmetro UserName no conjunto de parâmetros de usuário e um parâmetro de resumo em ambos os conjuntos de parâmetros.

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")]
            [String[]]
            $ComputerName,

            [parameter(Mandatory=$true,
                      ParameterSetName="User")]
            [String[]]
            $UserName,

            [parameter(Mandatory=$false)]
            [Switch]
            $Summary
          )

Você pode especificar apenas um valor de ParameterSetName em cada argumento e apenas um argumento ParameterSetName em cada atributo de parâmetro. Para indicar que um parâmetro é exibido em mais de um conjunto de parâmetros, adicione outros atributos de parâmetro.

O exemplo a seguir adiciona explicitamente o parâmetro de resumo para os conjuntos de parâmetros do computador e usuário. O parâmetro de resumo é obrigatório em um conjunto de parâmetro e opcional no outro.

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")]
            [String[]]
            $ComputerName,

            [parameter(Mandatory=$true,
                      ParameterSetName="User")]
            [String[]]
            $UserName,

            [parameter(Mandatory=$false, ParameterSetName="Computer")]
            [parameter(Mandatory=$true, ParameterSetName="User")]
            [Switch]
            $Summary
          )
        

Para obter mais informações sobre conjuntos de parâmetros, consulte "Conjuntos de parâmetros Cmdlet" na biblioteca MSDN em https://go.microsoft.com/fwlink/?LinkId=142183.

Argumento ValueFromPipeline

O argumento ValueFromPipeline indica que o parâmetro aceita entrada de um objeto de pipeline. Especifique esse argumento se a função aceita todo o objeto, não apenas uma propriedade do objeto.

O exemplo a seguir declara um parâmetro ComputerName como obrigatório e aceita um objeto que é passado para a função do pipeline.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          )

Argumento ValueFromPipelineByPropertyName

O argumento valueFromPipelineByPropertyName indica que o parâmetro aceita entrada de uma propriedade de um objeto de pipeline. A propriedade do objeto deve ter o mesmo nome ou alias como o parâmetro.

Por exemplo, se a função tiver um parâmetro ComputerName, e o objeto de pipe tiver uma propriedade ComputerName, o valor da propriedade ComputerName é atribuído ao parâmetro ComputerName da função.

O exemplo a seguir declara um parâmetro ComputerName é obrigatório e aceita a entrada da propriedade ComputerName do objeto que é passado para a função por meio do pipeline.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipelineByPropertyName=$true)]
            [String[]]
            $ComputerName
          )

Argumento ValueFromRemainingArguments

O argumento ValueFromRemainingArguments indica que o parâmetro aceita todos os valores de parâmetros no comando que não são atribuídos a outros parâmetros da função.

O exemplo a seguir declara um parâmetro ComputerName que é obrigatório e aceita todos os valores de parâmetro restantes que foram enviados para a função.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromRemainingArguments=$true)]
            [String[]]
            $ComputerName
          )

Argumento HelpMessage

O argumento HelpMessage especifica uma cadeia de caracteres que contém uma breve descrição do parâmetro ou de seu valor. o Windows PowerShell exibe essa mensagem no prompt que aparece quando um valor de parâmetro obrigatório está ausente num comando. Esse argumento não tem nenhum efeito sobre parâmetros opcionais.

O exemplo a seguir declara um parâmetro ComputerName obrigatório e uma mensagem de ajuda que explica o valor de parâmetro esperado.

        Param
          (
            [parameter(mandatory=$true,
                       HelpMessage="Enter one or more computer names separated by commas.")]
            [String[]]
            $ComputerName
          )

ATRIBUTO DE ALIAS

O atributo de Alias estabelece um nome alternativo para o parâmetro. Não há nenhum limite para o número de aliases que podem ser atribuídos a um parâmetro.

O exemplo a seguir mostra uma declaração de parâmetro que adiciona os aliases "CN" e "MachineName" para o parâmetro ComputerName obrigatório.

        Param
          (
            [parameter(Mandatory=$true)]
            [alias("CN","MachineName")]
            [String[]]
            $ComputerName
          )

ATRIBUTOS DE PARÂMETRO E VALIDAÇÃO DA VARIÁVEL

Atributos de validação direcionam o Windows PowerShell para testar os valores de parâmetro que os usuários enviam quando eles chamam a função avançada. Se os valores de parâmetro falharem no teste, será gerado um erro e a função não será chamada. Você também pode usar alguns dos atributos de validação para restringir os valores especificados pelos usuários para as variáveis.

Atributo de validação AllowNull

O atributo AllowNull permite que o valor de um parâmetro obrigatório seja nulo ($null). O exemplo a seguir declara um parâmetro ComputerName que pode ter um valor nulo.

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowNull()]
            [String]
            $ComputerName
          )

Atributo de validação AllowEmptyString

O atributo AllowEmptyString permite que o valor de um parâmetro obrigatório seja uma cadeia de caracteres vazia (""). O exemplo a seguir declara um parâmetro ComputerName que pode ter um valor de cadeia de caracteres vazio.

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowEmptyString()]
            [String]
            $ComputerName
          )

Atributo de validação AllowEmptyCollection

O atributo AllowEmptyCollection permite que o valor de um parâmetro obrigatório seja uma coleção vazia (@()). O exemplo a seguir declara um parâmetro ComputerName que pode ter um valor de coleção vazio.

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowEmptyCollection()]
            [String[]]
            $ComputerName
          )

Atributo de validação ValidateCount

O atributo ValidateCount especifica o número mínimo e máximo de valores de parâmetro que um parâmetro aceita. O Windows PowerShell gera um erro se o número de valores de parâmetros estiver fora desse limite no comando que chama a função.

A seguinte declaração de parâmetro cria um parâmetro ComputerName que usa valores de parâmetro de 1 a 5.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateCount(1,5)]
            [String[]]
            $ComputerName
          )

Atributo de validação ValidateLength

O atributo ValidateLength especifica o número mínimo e máximo de caracteres em um valor de parâmetro ou variável. O Windows PowerShell gera um erro se o valor especificado para o parâmetro ou variável estiver fora do limite.

No exemplo a seguir, cada nome do computador deve ter de um a 10 caracteres.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateLength(1,10)]
            [String[]]
            $ComputerName
          )

No exemplo a seguir, o valor da variável $number deve estar em um comprimento mínimo de um caractere e máximo de 10 caracteres.

        [Int32][ValidateLength(1,10)]$number = 01

Atributo de validação ValidatePattern

O atributo ValidatePattern especifica uma expressão regular que é comparada ao valor de parâmetro ou variável. O Windows PowerShell gera um erro se o valor não corresponder ao padrão de expressão regular.

No exemplo a seguir, o valor do parâmetro deve ser um número de quatro dígitos e cada dígito deve ser um número de 0 a 9.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidatePattern("[0-9][0-9][0-9][0-9]")]
            [String[]]
            $ComputerName
          )

No exemplo a seguir, o valor da variável $number deve ser um número de quatro dígitos e cada dígito deve ser um número de 0 a 9.

        [Int32][ValidatePattern("[0-9][0-9][0-9][0-9]")]$number = 1111

Atributo de validação ValidateRange

O atributo ValidateRange especifica um intervalo numérico para cada valor de parâmetro ou variável. O Windows PowerShell gera um erro se algum valor estiver fora desse limite. No exemplo a seguir, o valor do parâmetro de tentativas deve estar entre 0 e 10.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateRange(0,10)]
            [Int]
            $Attempts
          )

No exemplo a seguir, o valor da variável $number deve estar entre 0 e 10.

        [Int32][ValidateRange(0,10)]$number = 5

Atributo de validação ValidateScript

O atributo ValidateScript especifica um script usado para validar um valor de parâmetro ou variável. O Windows PowerShell redireciona o valor para o script, e gera um erro se o script retornar "false" ou se o script lançar uma exceção.

Quando você usa o atributo ValidateScript, o valor que está sendo validado é mapeado para $_ variable. Você pode usar $_ variable para se referir ao valor no script.

No exemplo a seguir, o valor do parâmetro EventDate deve ser maior ou igual à data atual.

        Param
          (
            [parameter()]
            [ValidateScript({$_ -ge (get-date)})]
            [DateTime]
            $EventDate
          )

No exemplo a seguir, o valor da variável $date deve ser maior ou igual à data e à hora atuais.

       [DateTime][ValidateScript({$_ -ge (get-date)})]$date = (get-date)

Atributo ValidateSet

O atributo ValidateSet especifica um conjunto de valores válidos para um parâmetro ou variável. O Windows PowerShell gera um erro se um valor de parâmetro ou variável não corresponder a um valor no conjunto. No exemplo a seguir, o valor do parâmetro detalhes só pode ser "Baixo", "Médio" ou "Alto".

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateSet("Low", "Average", "High")]
            [String[]]
            $Detail
          )

No exemplo a seguir, o valor da variável $flavor deve ser Chocolate, Morango e Baunilha.

        [String][ValidateSet("Chocolate", "Strawberry", "Vanilla")]$flavor = Strawberry

Atributo de validação ValidateNotNull

O atributo ValidateNotNull especifica que o valor do parâmetro não pode ser nulo ($null). O Windows PowerShell gera um erro se o valor do parâmetro for nulo.

O atributo ValidateNotNull é projetado para ser usado quando o tipo do valor do parâmetro não for especificado ou quando o tipo especificado aceitar um valor nulo. (Se você especificar um tipo que não aceita um valor nulo, como uma cadeia de caracteres, o valor nulo será rejeitado sem o atributo ValidateNotNull, porque ele não corresponde ao tipo especificado.)

No exemplo a seguir, o valor do parâmetro de ID não pode ser nulo.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNull()]
            $ID
          )

Atributo de validação ValidateNotNullOrEmpty

O atributo ValidateNotNullOrEmpty especifica que o valor do parâmetro não pode ser nulo ($null) e não pode ser uma cadeia de caracteres vazia (""). O Windows PowerShell gera um erro se o parâmetro for usado em uma chamada de função, mas seu valor for nulo, uma cadeia de caracteres vazia ou uma matriz vazia.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNullOrEmpty()]
            [String[]]
            $UserName
          )

PARÂMETROS DINÂMICOS

Parâmetros dinâmicos são parâmetros de cmdlet, função ou script disponíveis somente em determinadas condições.

Por exemplo, vários cmdlets do provedor têm parâmetros disponíveis somente quando o cmdlet é usado na unidade de provedor, ou em um caminho específico da unidade do provedor. Por exemplo, o parâmetro de codificação está disponível em cmdlets Add-Content, Get-Content e Set-Content apenas quando ele é usado em uma unidade de sistema de arquivos.

Você também pode criar um parâmetro aparece somente quando o outro parâmetro é usado no comando de função ou outro parâmetro tem um determinado valor.

Parâmetros dinâmicos podem ser muito úteis, mas use-os somente quando necessário, pois isso pode ser difícil para os usuários descobrirem. Para localizar um parâmetro dinâmico, o usuário deve estar no caminho de provedor, use o parâmetro ArgumentList do cmdlet Get-Command ou use o parâmetro Path de Get-Help.

Para criar um parâmetro dinâmico para uma função ou um script, use a palavra-chave DynamicParam.

A sintaxe é a seguinte:

      DynamicParam {<statement-list>}

Na lista de instrução, use uma instrução If para especificar as condições sob as quais o parâmetro está disponível na função.

Use o cmdlet New-Object para criar um objeto System.Management.Automation.RuntimeDefinedParameter para representar o parâmetro e especifique seu nome.

Você também pode usar um comando New-Object para criar um objeto de System.Management.Automation.ParameterAttribute para representar os atributos do parâmetro, como Obrigatório, Posição, ou ValueFromPipeline ou seu conjunto de parâmetros.

O exemplo a seguir mostra uma função de exemplo com os parâmetros padrão denominados Nome e Caminho e um parâmetro dinâmico opcional chamado DP1. O parâmetro DP1 está no conjunto de parâmetro PSet1 e tem um tipo de Int32. O parâmetro DP1 está disponível na função de exemplo somente quando o valor do parâmetro Caminho contém "HKLM:", indicando que ele está sendo usado na unidade de Registro HKEY_LOCAL_MACHINE.

    function Get-Sample {
        [CmdletBinding()]
        Param ([String]$Name, [String]$Path)
 
        DynamicParam
        {
            if ($path -match ".*HKLM.*:")
            {
                $attributes = new-object System.Management.Automation.ParameterAttribute
                $attributes.ParameterSetName = "__AllParameterSets"
                $attributes.Mandatory = $false
                $attributeCollection = new-object `
                    -Type System.Collections.ObjectModel.Collection[System.Attribute]
                $attributeCollection.Add($attributes)

                $dynParam1 = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection)
            
                $paramDictionary = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameterDictionary
                $paramDictionary.Add("dp1", $dynParam1)
                return $paramDictionary
            }
        }
    }

Para mais informações, consulte "RuntimeDefinedParameter Class" na biblioteca MSDN (Microsoft Developer Network) em https://go.microsoft.com/fwlink/?LinkID=145130.

Parâmetros de opção

Parâmetros de opção são parâmetros sem nenhum valor de parâmetro. Eles são efetivos somente quando são usados e têm apenas um efeito.

Por exemplo, o parâmetro - NoProfile de PowerShell.exe é um parâmetro de opção.

Para criar um parâmetro de opção em uma função, especifique o tipo de opção na definição de parâmetro.

    For example:
        Param ([Switch]<ParameterName>)
    -or- 
        Param
          (
             [parameter(Mandatory=$false)]
             [Switch]
             $<ParameterName>
          )

Parâmetros de opção são fáceis de usar e têm preferência sobre parâmetros boolianos, os quais apresentam uma sintaxe mais difícil.

Por exemplo, para usar um parâmetro de opção, o usuário digita o parâmetro no comando.

        -IncludeAll

Para usar um parâmetro booliano, o usuário digita o parâmetro e um valor booliano.

        -IncludeAll:$true

Ao criar parâmetros de opção, escolha o nome do parâmetro com cuidado. Certifique-se de que o nome do parâmetro comunica o efeito do parâmetro para o usuário e evite termos ambíguos, como filtro ou máximo, que podem indicar que um valor é necessário.

CONSULTE TAMBÉM

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute