TÓPICO
    about_Functions_Advanced_Parameters

DESCRIÇÃO RESUMIDA
    Explica como adicionar parâmetros estáticos e dinâmicos a funções
    que declaram o atributo CmdletBinding.

DESCRIÇÃO LONGA
    Você pode declarar seus próprios parâmetros quando escreve 
    funções, e pode escrever funções de forma que elas possam acessar os 
    parâmetros comuns disponíveis para cmdlets compilados. Para obter mais 
    informações sobre os parâmetros comuns do Windows PowerShell, consulte 
    about_CommonParameters.

Parâmetros estáticos
    O exemplo a seguir mostra uma declaração de parâmetro que define um 
    parâmetro ComputerName. Esse parâmetro tem as seguintes características:

        - Ele é obrigatório.
        - Ele pega a entrada do pipeline.
        - Ele pega uma matriz de cadeias de caracteres como entrada.

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

    O único atributo exigido que deve ser usado quando você declara 
    parâmetro é o atributo Parameter. Porém, você também pode declarar o 
    atributo Alias e vários argumentos de validação. Não há nenhum limite 
    ao número de atributos que você pode adicionar a uma declaração de 
    parâmetro.


  Atributo Parameter

      O atributo Parameter é usado para declarar um parâmetro da função.
      Este atributo tem os seguintes argumentos nomeados que são 
      usados para definir as características do parâmetro, por 
      exemplo, se o parâmetro é obrigatório ou opcional.


    Argumento nomeado Mandatory

        O argumento Mandatory indica que o parâmetro é obrigatório 
        quando a função é executada. Se esse argumento não for 
        especificado, o parâmetro será opcional. O exemplo a seguir 
        mostra a declaração de um parâmetro que é exigido quando a 
        função é executada.

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


    Argumento nomeado Position

        O argumento Position especifica a posição do parâmetro. Se esse 
        argumento não for especificado, o nome de parâmetro ou seu alias 
        deverá ser especificado explicitamente quando o parâmetro for 
        definido. Além disso, se nenhum dos parâmetros de uma função tiver 
        posições, o tempo de execução do Windows PowerShell atribuirá 
        posições a cada parâmetro com base na ordem na qual os parâmetros  
        são recebidos. 

        O exemplo a seguir mostra a declaração de um parâmetro cujo 
        valor deve ser especificado como o primeiro argumento quando 
        o cmdlet é executado. Observe que essa função pode ser 
        executada com ou sem a especificação do nome do parâmetro.

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


    Argumento nomeado ParameterSetName

        O argumento ParameterSetName especifica o conjunto de 
        parâmetros ao qual um parâmetro pertence. Se nenhum conjunto de 
        parâmetros for especificado, o parâmetro pertencerá a todos os 
        conjuntos de parâmetros definidos pela função. Este comportamento 
        significa que cada conjunto de parâmetros deve ter um parâmetro 
        exclusivo que não seja membro de nenhum outro conjunto de parâmetros. 
        O exemplo a seguir mostra a declaração de dois parâmetros que 
        pertencem a dois conjuntos de parâmetros diferentes. 

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

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

        Para obter mais informações sobre conjuntos de parâmetros, 
        consulte "Cmdlet Parameter Sets" (em inglês) na biblioteca do 
        MSDN em https://go.microsoft.com/fwlink/?LinkId=142183.


    Argumento nomeado ValueFromPipeline

        O argumento ValueFromPipeline especifica que o parâmetro 
        aceita entrada de um objeto de pipeline. Especifique esse 
        argumento se o cmdlet acessar o objeto completo, não apenas uma 
        propriedade do objeto. O exemplo a seguir mostra a declaração de um 
        parâmetro ComputerName obrigatório que aceita o objeto de entrada 
        transmitido para a função a partir do pipeline.

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


    Argumento nomeado ValueFromPipelineByPropertyName

        O argumento valueFromPipelineByPropertyName especifica que o 
        parâmetro aceita entrada de uma propriedade de um objeto de 
        pipeline. Especifique esse atributo se as condições a seguir forem 
        verdadeiras:

            - O parâmetro acessa uma propriedade do objeto enviado.

            - A propriedade tem o mesmo nome como o parâmetro ou a 
              propriedade tem o mesmo alias como o parâmetro.

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

        O exemplo a seguir mostra a declaração de um parâmetro 
        ComputerName que aceita entrada da propriedade ComputerName 
        do objeto de entrada que é transmitido ao cmdlet.

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


    Argumento nomeado ValueFromRemainingArguments

        O argumento ValueFromRemainingArguments especifica que o parâmetro 
        aceita todos os argumentos restantes que não estão associados aos 
        parâmetros da função. O exemplo a seguir mostra a declaração de um 
        parâmetro ComputerName que aceita todos os argumentos restantes do 
        objeto de entrada transmitido para a função.

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


    Argumento nomeado HelpMessage

        O argumento HelpMessage especifica uma mensagem que contém 
        uma descrição resumida do parâmetro. O exemplo a seguir mostra uma 
        declaração de parâmetro com uma descrição.

        Param
          (
            [parameter(Mandatory=$true,
                      HelpMessage="An array of computer names.")] 
            [String[]]
            $ComputerName
          ) 


  Atributo Alias

      O atributo Alias especifica outro nome para o parâmetro. Não há 
      nenhum limite de número de aliases que podem ser atribuídos a 
      um parâmetro. O exemplo a seguir mostra uma declaração de parâmetro 
      obrigatório que adiciona o alias "CN" ao parâmetro ComputerName.

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


  Atributos Parameter de validação

      Estes atributos definem como o tempo de execução do Windows 
      PowerShell valida os argumentos de funções avançadas.


    Atributo AllowNull de validação

        O atributo AllowNull permite que o argumento de um parâmetro 
        de cmdlet obrigatório seja definido como Nulo. No exemplo a 
        seguir, o parâmetro ComputerName pode conter um valor Nulo 
        embora este parâmetro seja obrigatório. 

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


    Atributo AllowEmptyString de validação

        O atributo AllowEmptyString permite que uma cadeia de 
        caracteres vazia seja o argumento de um parâmetro de cmdlet 
        obrigatório. No exemplo a seguir, o parâmetro ComputerName 
        pode conter uma cadeia de caracteres vazia (""), embora esse 
        parâmetro seja obrigatório. 

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


    Atributo AllowEmptyCollection de validação

        O atributo AllowEmptyCollection permite que uma coleção vazia 
        seja o argumento de um parâmetro obrigatório. 

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


    Atributo ValidateCount de validação

        O atributo ValidateCount especifica o número mínimo e máximo de 
        argumentos que o parâmetro pode aceitar. O tempo de execução do Windows 
        PowerShell gerará um erro se o número de argumentos estiver fora daquele 
        intervalo. No exemplo a seguir, o parâmetro ComputerName pode ter de 
        um a cinco argumentos. 

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


    Atributo ValidateLength de validação

        O atributo ValidateLength especifica o comprimento mínimo e 
        máximo do argumento do parâmetro. O tempo de execução do Windows 
        PowerShell gerará um erro se o comprimento do argumento do parâmetro 
        estiver fora daquele intervalo.
        No exemplo a seguir, os nomes de computador especificados 
        devem ter de um a 10 caracteres. 

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


    Atributo ValidatePattern de validação

        O atributo ValidatePattern especifica uma expressão regular 
        que valida o padrão do argumento do parâmetro. O tempo de 
        execução do Windows PowerShell gerará um erro se o argumento do 
        parâmetro não corresponder a esse padrão. No exemplo a seguir, o 
        argumento 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)]
            [String[]]
            [ValidatePattern("[0-9][0-9][0-9][0-9]")] 
            $ComputerName
          ) 


    Atributo ValidateRange de validação

        O atributo ValidateRange especifica os valores mínimo e máximo do 
        argumento do parâmetro. O tempo de execução do Windows PowerShell 
        gerará um erro se o argumento do parâmetro estiver fora daquele 
        intervalo. No exemplo a seguir, o argumento do parâmetro não pode ser 
        menor que 0 ou maior que 10. 


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


    Atributo ValidateScript de validação

        O atributo ValidateScript especifica um script que é usado 
        para validar o argumento do parâmetro. O tempo de execução do 
        Windows PowerShell gerará um erro se o resultado de script 
        for false ou se o script lançar uma exceção. No exemplo a 
        seguir, o valor do parâmetro Count deve ser menor que 4.

        Param
          (
            [parameter()]
            [Int]
            [ValidateScript({$_ -lt 4})]
            $Count
          ) 


    Atributo ValidateSet

        O atributo ValidateSet especifica um conjunto de valores 
        válidos para o argumento do parâmetro. O tempo de execução do 
        Windows PowerShell gerará um erro se o argumento do parâmetro não 
        corresponder a um valor no conjunto.
        No exemplo a seguir, o argumento do parâmetro pode conter só 
        os nomes Pedro, Maria e Carlos. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateRange("Pedro", "Maria", "Carlos")] 
            $UserName
          ) 


    Atributo ValidateNotNull de validação


        O atributo ValidateNotNull especifica que o argumento do 
        parâmetro não pode ser definido como Nulo. O tempo de execução do 
        Windows PowerShell gerará um erro se o valor do parâmetro for Nulo.  

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


    Atributo ValidateNotNullOrEmpty de validação

        O atributo ValidateNotNullOrEmpty especifica que o argumento do 
        parâmetro não pode ser definido como Nulo nem ficar em branco. O tempo 
        de execução do Windows PowerShell gerará um erro se o parâmetro for 
        especificado mas seu valor for Nulo, uma cadeia de caracteres vazia 
        ou uma matriz vazia.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateNotNullOrEmpty()]
            $UserName
          ) 
Parâmetros dinâmicos 
       Os parâmetros dinâmicos são parâmetros de um cmdlets, função ou 
       script disponíveis apenas sob determinadas condições. 
        
       Por exemplo, os cmdlets de vários fornecedores têm parâmetros que
       estão disponíveis apenas quando o cmdlet é usado no caminho do provedor. 
       Um parâmetro dinâmico conhecido é o parâmetro Encoding do cmdlet Set-Item,
       que está disponível apenas quando o cmdlet Set-Item é usado no caminho de
       provedor FileSystem.

       Para criar um parâmetro dinâmico para uma função ou script, use a 
       palavra-chave DynamicParam. 
 
A sintaxe é a seguinte. 
      
          DynamicParam {<statement-list>}  
      
       Na lista de instruções, use uma instrução If para especificar as 
       condições nas 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 especificar seu nome.  
      
       Você também pode usar um comando New-Object para criar um objeto 
       System.Management.Automation.ParameterAttribute para representar atributos 
       do parâmetro, como Mandatory, Position ou ValueFromPipeline ou seu conjunto de parâmetros. 
      
       O exemplo a seguir mostra uma função de amostra com parâmetros padrão denominados
       Name e Path, e um parâmetro dinâmico opcional denominado DP1. O parâmetro DP1 está 
       no conjunto de parâmetros PSet1 e tem um tipo Int32. O parâmetro DP1 está disponível na 
       função Sample somente quando o valor do parâmetro Path contém "HKLM:", indicando que ele 
       está sendo usado na unidade do Registro HKEY_LOCAL_MACHINE.
      
      
        function Sample { 
          Param ([String]$Name, [String]$Path) 
      
          DynamicParam 
          { 
            if ($path -match "*HKLM*:") 
            { 
              $dynParam1 = new-object  
                System.Management.Automation.RuntimeDefinedParameter("dp1", 
                [Int32], $attributeCollection) 
      
              $attributes = new-object System.Management.Automation.ParameterAttribute 
              $attributes.ParameterSetName = 'pset1' 
              $attributes.Mandatory = $false 
      
              $attributeCollection = new-object  
                -Type System.Collections.ObjectModel.Collection``1[System.Attribute] 
              $attributeCollection.Add($attributes) 
     
              $paramDictionary = new-object  
                System.Management.Automation.RuntimeDefinedParameterDictionary 
              $paramDictionary.Add("dp1", $dynParam1) 
             
              return $paramDictionary 
            } End if 
          } 
        }   
      
        Para obter mais informações, consulte "RuntimeDefinedParameter Class" na
        biblioteca do MSDN (Microsoft Developer Network) em 
        https://go.microsoft.com/fwlink/?LinkID=145130 (site em inglês).




CONSULTE TAMBÉM
    about_Advanced_Functions
    about_Functions_Advanced_Methods
    about_Functions_CmdletBindingAttribute  




Sumário