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