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