about_Functions_Advanced_Parameters
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 usar atributos e argumentos de parâmetro 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 os usuários, além dos parâmetros comuns que o PowerShell adiciona automaticamente a todos os cmdlets e funções avançadas. Para obter mais informações sobre os parâmetros comuns do PowerShell, consulte about_CommonParameters.
A partir do PowerShell 3.0, você pode usar o splatting com @Args para representar os parâmetros em um comando. O splatting é válido em funções simples e avançadas. Para obter mais informações, consulte about_Functions e about_Splatting.
Conversão de tipo de valores de parâmetro
Quando você fornece cadeias de caracteres como argumentos para parâmetros que esperam um tipo diferente, o PowerShell converte implicitamente as cadeias de caracteres para o tipo de destino do parâmetro. As funções avançadas executam a análise invariante de cultura dos valores dos parâmetros.
Por outro lado, uma conversão sensível à cultura é executada durante a vinculação de parâmetros para cmdlets compilados.
Neste exemplo, criamos um cmdlet e uma função de script que usam um [datetime] parâmetro. A cultura atual é alterada para usar configurações alemãs.
Uma data formatada em alemão é passada para o parâmetro.
# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
using System;
using System.Management.Automation;
[Cmdlet("Get", "Date_Cmdlet")]
public class GetFooCmdlet : Cmdlet {
[Parameter(Position=0)]
public DateTime Date { get; set; }
protected override void ProcessRecord() {
WriteObject(Date);
}
}
'@ -PassThru | % Assembly | Import-Module
[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'
Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00
Como mostrado acima, os cmdlets usam análise sensível à cultura para converter a cadeia de caracteres.
# Define an equivalent function.
function Get-Date_Func {
param(
[DateTime] $Date
)
process {
$Date
}
}
[cultureinfo]::CurrentCulture = 'de-DE'
# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'
Get-Date_Func $dateStr
As funções avançadas usam análise invariante de cultura, o que resulta no seguinte erro.
Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."
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 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 (obrigatório).
- Ele recebe a entrada do pipeline.
- Ele usa uma matriz de cadeias de caracteres como entrada.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
Parâmetros de opção
Os parâmetros de opção são parâmetros que não têm valor de parâmetro. Em vez disso, eles transmitem um valor booleano verdadeiro ou falso através de sua presença ou ausência, de modo que quando um parâmetro de switch está presente ele tem um valor verdadeiro e quando ausente ele tem um valor falso .
Por exemplo, o parâmetro Recurse de é um parâmetro de Get-ChildItem opção.
Para criar um parâmetro de opção em uma função, especifique o switch tipo na definição de parâmetro.
Por exemplo, sua função pode ter uma opção para gerar dados como uma matriz de bytes:
param([switch]$AsByteArray)
Os parâmetros de switch são fáceis de usar e são preferidos em relação aos parâmetros booleanos, que têm uma sintaxe menos natural para o PowerShell.
Por exemplo, para usar um parâmetro switch, o usuário digita o parâmetro no comando.
-IncludeAll
Para usar um parâmetro booleano, o usuário digita o parâmetro e um valor booleano.
-IncludeAll $true
Ao criar parâmetros de opção, escolha o nome do parâmetro cuidadosamente. Certifique-se de que o nome do parâmetro comunica o efeito do parâmetro ao usuário. Evite termos ambíguos, como Filtro ou Máximo , que possam implicar que um valor é necessário.
Considerações sobre o design do parâmetro de opção
Os parâmetros de alternância não devem receber valores padrão. Eles devem sempre padronizar como falso.
Os parâmetros de comutação são excluídos dos parâmetros posicionais por padrão. Mesmo quando outros parâmetros são implicitamente posicionais, os parâmetros de switch não são. Você pode substituir isso no atributo Parameter, mas isso confundirá os usuários.
Os parâmetros de alternância devem ser projetados para que defini-los mova um comando de seu comportamento padrão para um modo menos comum ou mais complicado. O comportamento mais simples de um comando deve ser o comportamento padrão que não requer o uso de parâmetros de opção.
Os parâmetros de troca não devem ser obrigatórios. O único caso em que é necessário tornar um parâmetro de switch obrigatório é quando ele é necessário para diferenciar um conjunto de parâmetros.
A configuração explícita de um interruptor de um booleano pode ser feita com
-MySwitch:$boolValuee em splatting com$params = @{ MySwitch = $boolValue }.Os parâmetros de switch são do tipo
SwitchParameter, que implicitamente converte em booleano. A variável de parâmetro pode ser usada diretamente em uma expressão condicional. Por exemplo:if ($MySwitch) { ... }Não há necessidade de escrever
if ($MySwitch.IsPresent) { ... }
Parâmetros dinâmicos
Parâmetros dinâmicos são parâmetros de um cmdlet, função ou script que estão disponíveis somente sob determinadas condições.
Por exemplo, vários cmdlets de provedor têm parâmetros que estão disponíveis somente quando o cmdlet é usado na unidade do provedor ou em um caminho específico da unidade do provedor. Por exemplo, o parâmetro Encoding está disponível nos Add-Contentcmdlets , Get-Contente Set-Content somente quando é usado em uma unidade do sistema de arquivos.
Você também pode criar um parâmetro que aparece somente quando outro parâmetro é usado no comando function ou quando outro parâmetro tem um determinado valor.
Os parâmetros dinâmicos podem ser úteis, mas use-os apenas quando necessário, porque podem ser difíceis de serem descobertos pelos usuários. Para localizar um parâmetro dinâmico, o usuário deve estar no caminho do provedor, usar o parâmetro ArgumentList do Get-Command cmdlet ou usar o parâmetro Path de Get-Help.
Para criar um parâmetro dinâmico para uma função ou script, use a DynamicParam palavra-chave.
A sintaxe dela é a seguinte:
dynamicparam {<statement-list>}
Na lista de instruções, use uma if instrução para especificar as condições sob as quais o parâmetro está disponível na função.
O exemplo a seguir mostra uma função com parâmetros padrão chamados Name e Path e um parâmetro dinâmico opcional chamado KeyCount. O parâmetro KeyCount está no ByRegistryPath conjunto de parâmetros e tem um tipo de Int32. O parâmetro KeyCount está disponível na Get-Sample função somente quando o valor do parâmetro Path começa com HKLM:, indicando que ele está sendo usado na unidade do HKEY_LOCAL_MACHINE Registro.
function Get-Sample {
[CmdletBinding()]
param([string]$Name, [string]$Path)
DynamicParam
{
if ($Path.StartsWith("HKLM:"))
{
$parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
ParameterSetName = "ByRegistryPath"
Mandatory = $false
}
$attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
$attributeCollection.Add($parameterAttribute)
$dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
'KeyCount', [Int32], $attributeCollection
)
$paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
$paramDictionary.Add('KeyCount', $dynParam1)
return $paramDictionary
}
}
}
Para obter mais informações, consulte a documentação do tipo RuntimeDefinedParameter .
Atributos dos 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 reconhecido como uma função avançada, a função deverá incluir o atributo Parameter .
Você pode adicionar um ou vários atributos em cada declaração de parâmetro. Não há limite para o número de atributos que você pode adicionar a uma declaração de parâmetro.
Atributo de parâmetro
O atributo Parameter é usado para declarar os atributos dos parâmetros de função.
O atributo Parameter é 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 Parameter , ou ambos.
O atributo Parameter tem argumentos que definem as características do parâmetro, como se o parâmetro é obrigatório ou opcional.
Use a sintaxe a seguir para declarar o atributo Parameter , um argumento e um valor de argumento. Os parênteses que encerram o argumento e seu valor devem seguir Parameter sem espaço interveniente.
param(
[Parameter(Argument=value)]
$ParameterName
)
Use vírgulas para separar argumentos entre parênteses. Use a sintaxe a seguir para declarar dois argumentos do atributo Parameter .
param(
[Parameter(Argument1=value1, Argument2=value2)]
$ParameterName
)
Os tipos de argumento booleano do atributo Parameter têm como padrão False quando omitidos do atributo Parameter . Defina o valor do argumento como $true ou apenas liste o argumento por nome. Por exemplo, os seguintes atributos Parameter são equivalentes.
param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
param(
[Parameter(Mandatory)]
)
Se você usar o atributo Parameter 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 Mandatory argumento indica que o parâmetro é necessário. Se esse argumento não for especificado, o parâmetro será opcional.
O exemplo a seguir declara o parâmetro ComputerName . Ele usa o Mandatory argumento para tornar o parâmetro obrigatório.
param(
[Parameter(Mandatory)]
[string[]]$ComputerName
)
Argumento de posição
O Position argumento 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 Position argumento, o nome do parâmetro pode ser omitido e o 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 Position argumento não for especificado, o nome do parâmetro, ou um alias ou abreviação do nome do parâmetro, deverá 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 PowerShell atribui números de posição aos parâmetros na ordem em que os parâmetros são declarados na função.
Para desabilitar esse recurso, defina o PositionalBinding valor do argumento do atributo CmdletBinding como $False. O Position argumento tem precedência sobre o PositionalBinding valor do argumento do atributo CmdletBinding . Para obter mais informações, consulte PositionalBinding em about_Functions_CmdletBindingAttribute.
O valor do Position argumento é especificado como um inteiro. Um valor de posição de 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 PowerShell atribuirá posições a cada parâmetro com base na ordem em que os parâmetros são declarados. No entanto, como prática recomendada, não confie nessa atribuição. Quando quiser que os parâmetros sejam posicionais, use o Position argumento.
O exemplo a seguir declara o parâmetro ComputerName . Ele usa o Position argumento com um valor de 0. Como resultado, quando -ComputerName é omitido do comando, seu valor deve ser o primeiro ou único valor de parâmetro sem nome no comando.
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
Argumento ParameterSetName
O ParameterSetName argumento 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. Para ser exclusivo, cada conjunto de parâmetros deve ter pelo menos um parâmetro que não seja membro de nenhum outro conjunto de parâmetros.
Observação
Para um cmdlet ou função, há um limite de 32 conjuntos de parâmetros.
O exemplo a seguir declara um parâmetro ComputerName no Computer conjunto de parâmetros, um parâmetro UserName no User conjunto de parâmetros e um parâmetro Summary em ambos os conjuntos de parâmetros.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter()]
[switch]$Summary
)
Você pode especificar apenas um ParameterSetName valor em cada argumento e apenas um ParameterSetName argumento em cada atributo Parameter . Para incluir um parâmetro em mais de um conjunto de parâmetros, adicione atributos Parameter adicionais.
O exemplo a seguir adiciona explicitamente o parâmetro Summary aos Computer conjuntos de parâmetros e User . O parâmetro Summary é opcional no Computer conjunto de parâmetros e obrigatório no conjunto de User parâmetros.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, ParameterSetName="User")]
[switch]$Summary
)
Para obter mais informações sobre conjuntos de parâmetros, consulte Sobre conjuntos de parâmetros.
Argumento ValueFromPipeline
O ValueFromPipeline argumento indica que o parâmetro aceita entrada de um objeto de pipeline. Especifique esse argumento se a função aceitar o objeto inteiro, não apenas uma propriedade do objeto.
O exemplo a seguir declara um parâmetro ComputerName que é obrigatório e aceita um objeto que é passado para a função do pipeline.
param(
[Parameter(Mandatory, ValueFromPipeline)]
[string[]]$ComputerName
)
Argumento ValueFromPipelineByPropertyName
O ValueFromPipelineByPropertyName argumento indica que o parâmetro aceita entrada de uma propriedade de um objeto de pipeline. A propriedade object deve ter o mesmo nome ou alias que o parâmetro.
Por exemplo, se a função tiver um parâmetro ComputerName e o objeto canalizado tiver uma propriedade ComputerName, o valor da propriedade ComputerName será atribuído ao parâmetro ComputerName da função.
O exemplo a seguir declara um parâmetro ComputerName que é obrigatório e aceita entrada da propriedade ComputerName do objeto que é passada para a função através do pipeline.
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Considere uma implementação de uma função usando este argumento:
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
Em seguida, uma demonstração de canalização de um objeto com a propriedade ComputerName seria:
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
Observação
Um parâmetro tipado que aceita entrada de pipeline (by Value) ou (by PropertyName) permite o uso de blocos de script de vinculação de atraso no parâmetro.
O bloco de script de ligação de atraso é executado automaticamente durante ParameterBinding. O resultado está vinculado ao parâmetro. A vinculação de atraso não funciona para parâmetros definidos como tipo ScriptBlock ou System.Object. O bloco de script é passado sem ser invocado. Para obter mais informações sobre blocos de script de vinculação de atraso, consulte about_Script_Blocks.
Argumento ValueFromRemainingArguments
O ValueFromRemainingArguments argumento indica que o parâmetro aceita todos os valores do parâmetro no comando que não são atribuídos a outros parâmetros da função.
O exemplo a seguir declara um parâmetro Value que é obrigatório e um parâmetro Remaining que aceita todos os valores de parâmetro restantes que são enviados para a função.
function Test-Remainder {
param(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(Position=1, ValueFromRemainingArguments)]
[string[]]$Remaining
)
"Found $($Remaining.Count) elements"
for ($i = 0; $i -lt $Remaining.Count; $i++) {
"${i}: $($Remaining[$i])"
}
}
Test-Remainder first one,two
Found 2 elements
0: one
1: two
Argumento HelpMessage
O HelpMessage argumento especifica uma cadeia de caracteres que contém uma breve descrição do parâmetro ou de seu valor. Se você executar o comando sem o parâmetro obrigatório, o PowerShell solicitará a entrada. Para ver a mensagem de ajuda, digite !? no prompt e pressione Enter.
O exemplo a seguir declara um parâmetro ComputerName obrigatório e uma mensagem de ajuda que explica o valor do parâmetro esperado.
param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]$ComputerName
)
Exemplo de saída:
cmdlet at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:
Se não houver nenhuma ajuda baseada em comentários para a função, essa mensagem será exibida na Get-Help -Full saída.
Esse argumento não tem efeito sobre parâmetros opcionais.
Atributo Alias
O atributo Alias estabelece um nome alternativo para o parâmetro. Não há limite para o número de aliases que você pode atribuir a um parâmetro.
O exemplo a seguir mostra uma declaração de parâmetro que adiciona os aliases CN e MachineName ao parâmetro ComputerName obrigatório.
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
Atributo de credencial
O atributo Credential é usado para indicar que o parâmetro aceita credenciais. O exemplo a seguir mostra uma declaração de parâmetro que usa o atributo Credential .
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
Atributo experimental
Use o atributo Experimental para declarar algum código como experimental. Para obter uma descrição completa do atributo, consulte about_Experimental_Features.
Atributo PSDefaultValue
O PSDefaultValue especifica o valor padrão de um parâmetro de comando em um script. Essas informações são exibidas Get-Help pelo cmdlet. Para ver as informações de valor padrão, a função deve incluir ajuda baseada em comentários. Por exemplo:
<#
.SYNOPSIS
This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
param(
[PSDefaultValue(Help='Current directory')]
[string]$Name = $PWD.Path
)
$Name
}
Use Get-Help para ver as informações de valor padrão.
Get-Help TestDefaultValue -Parameter name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
Argumentos do atributo PSDefaultValue
O atributo PSDefaultValue tem dois argumentos:
- Ajuda - Uma cadeia de caracteres que descreve o valor padrão. Essas informações são exibidas
Get-Helppelo cmdlet. - Valor - O valor padrão do parâmetro.
Ambos os argumentos são opcionais. Se você não especificar nenhum argumento, Get-Help mostrará o valor atribuído ao parâmetro.
Atributo PSTypeName
Não é possível usar nomes de tipo estendidos em uma declaração de tipo. O atributo PSTypeName* permite restringir o tipo do parâmetro ao tipo estendido.
Neste exemplo, o Test-Connection cmdlet retorna um tipo estendido. Você pode usar o atributo PSTypeName para restringir o tipo do parâmetro ao tipo estendido.
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
Atributo System.Obsolete
Use o atributo System.Obsolete para marcar parâmetros que não são mais suportados. Isso pode ser útil quando você deseja remover um parâmetro de uma função, mas não deseja interromper os scripts existentes que usam a função.
Por exemplo, considere uma função que tenha um parâmetro de opção NoTypeInformation que controla se as informações de tipo estão incluídas na saída. Você deseja tornar esse comportamento o padrão e remover o parâmetro da função. No entanto, você não deseja quebrar scripts existentes que usam a função. Você pode marcar o parâmetro como obsoleto e adicionar uma mensagem que explique a alteração.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
Atributo SupportsWildcards
O atributo SupportsWildcards é usado para indicar que o parâmetro aceita valores curinga. O exemplo a seguir mostra uma declaração de parâmetro para um parâmetro Path obrigatório que oferece suporte a valores curinga.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
O uso desse atributo não habilita automaticamente o suporte a curingas. O desenvolvedor do cmdlet deve implementar o código para manipular a entrada curinga. Os curingas com suporte podem variar de acordo com a API subjacente ou o provedor do PowerShell. Para obter mais informações, consulte about_Wildcards.
Atributos de conclusão de argumento
Atributo ArgumentCompletions
O atributo ArgumentCompletions permite adicionar valores de conclusão de tabulação a um parâmetro específico. Um atributo ArgumentCompletions deve ser definido para cada parâmetro que precisa de conclusão de tabulação. O atributo ArgumentCompletions é semelhante a ValidateSet. Ambos os atributos usam uma lista de valores a serem apresentados quando o usuário pressiona Tab após o nome do parâmetro. No entanto, ao contrário de ValidateSet, os valores não são validados.
Esse atributo foi introduzido no PowerShell 6.0.
Para obter mais informações, consulte about_Functions_Argument_Completion.
Atributo ArgumentCompleter
O atributo ArgumentCompleter permite adicionar valores de conclusão de tabulação a um parâmetro específico. Um atributo ArgumentCompleter deve ser definido para cada parâmetro que precisa de conclusão de tabulação. Como DynamicParameters, os valores disponíveis são calculados em tempo de execução quando o usuário pressiona Tab após o nome do parâmetro.
Para obter mais informações, consulte about_Functions_Argument_Completion.
Atributos de validação de parâmetros e variáveis
Os atributos de validação direcionam o PowerShell para testar os valores de parâmetro que os usuários enviam quando chamam a função avançada. Se os valores de parâmetro falharem no teste, um erro será gerado e a função não será chamada. A validação de parâmetro é aplicada apenas à entrada fornecida e quaisquer outros valores, como valores padrão, não são validados.
Você também pode usar os atributos de validação para restringir os valores que os usuários podem especificar para variáveis.
[AllowNull()] [int]$number = 7
Os atributos de validação podem ser aplicados a qualquer variável, não apenas a parâmetros. Você pode definir validação para qualquer variável dentro de um script.
Observação
Ao usar quaisquer atributos com uma variável digitada, é uma prática recomendada declarar o atributo antes do tipo.
Se você declarar um tipo com uma quebra de linha antes do atributo e do nome da variável, o tipo será tratado como sua própria instrução.
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
Se você declarar um atributo de validação após um tipo, o valor que está sendo atribuído será validado antes da conversão de tipo, o que pode levar a falhas inesperadas de validação.
[string] [ValidateLength(1,5)]$TicketIDFromInt = 43
[string] [ValidateLength(1,5)]$TicketIDFromString = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43
MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.
Atributo de validação AllowNull
O atributo AllowNull permite que o valor de um parâmetro obrigatório seja $null. O exemplo a seguir declara um parâmetro ComputerInfo hashtable que pode ter um valor nulo.
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
Observação
O atributo AllowNull não funcionará se o conversor de tipo estiver definido como string, pois o tipo de cadeia de caracteres não aceitará um valor nulo. Você pode usar o atributo AllowEmptyString para esse cenário.
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)]
[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)]
[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 PowerShell gerará um erro se o número de valores de parâmetro no comando que chama a função estiver fora desse intervalo.
A declaração de parâmetro a seguir cria um parâmetro ComputerName que leva de um a cinco valores de parâmetro.
param(
[Parameter(Mandatory)]
[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 PowerShell gerará um erro se o comprimento de um valor especificado para um parâmetro ou uma variável estiver fora do intervalo.
No exemplo a seguir, cada nome de computador deve ter de um a dez caracteres.
param(
[Parameter(Mandatory)]
[ValidateLength(1,10)]
[string[]]$ComputerName
)
No exemplo a seguir, o valor da variável $text deve ter no mínimo um caractere e no máximo dez caracteres.
[ValidateLength(1,10)] [string] $text = 'valid'
Atributo de validação ValidatePattern
O atributo ValidatePattern especifica uma expressão regular que é comparada ao valor do parâmetro ou da variável. O PowerShell gerará 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 conter um número de quatro dígitos e cada dígito deve ser um número de zero a nove.
param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9]{4}")]
[string[]]$ComputerName
)
No exemplo a seguir, o valor da variável $ticketID deve ser exatamente um número de quatro dígitos e cada dígito deve ser um número de zero a nove.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111
Atributo de validação ValidateRange
O atributo ValidateRange especifica um intervalo numérico ou um valor de enum ValidateRangeKind para cada parâmetro ou valor de variável. O PowerShell gerará um erro se qualquer valor estiver fora desse intervalo.
O enum ValidateRangeKind permite os seguintes valores:
- Positivo - Um número maior que zero.
- Negativo - Um número menor que zero.
- Não Positivo - Um número menor ou igual a zero.
- Não Negativo - Um número maior ou igual a zero.
No exemplo a seguir, o valor do parâmetro Attempts deve estar entre zero e dez.
param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[Int]$Attempts
)
No exemplo a seguir, o valor da variável $number deve estar entre zero e dez.
[ValidateRange(0,10)] [int]$number = 5
No exemplo a seguir, o valor da variável $number deve ser maior que zero.
[ValidateRange("Positive")] [int]$number = 1
Atributo de validação ValidateScript
O atributo ValidateScript especifica um script usado para validar um valor de parâmetro ou variável. O PowerShell canaliza 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 a $_ variável. Você pode usar a $_ variável para fazer referência ao valor no script.
No exemplo a seguir, o valor do parâmetro EventDate deve ser maior ou igual à data atual.
param(
[Parameter(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]$EventDate
)
No exemplo a seguir, o valor da variável $date deve ser menor ou igual à data e hora atuais.
[ValidateScript({$_ -le (Get-Date)})] [DateTime]$date = (Get-Date)
Observação
Se você usar ValidateScript, não poderá passar um $null valor para o parâmetro. Quando você passa um valor nulo, ValidateScript não pode validar o argumento.
Substituindo a mensagem de erro padrão
A partir do PowerShell 6, você pode substituir a mensagem de erro padrão gerada quando um valor especificado é inválido com o ErrorMessage argumento. Especifique uma cadeia de caracteres de formato composto. O 0 componente de índice usa o valor de entrada.
O 1 componente de índice usa o ScriptBlock usado para validar o valor de entrada.
No exemplo a seguir, o valor do parâmetro EventDate deve ser maior ou igual à data e hora atuais. Se o valor for inválido, a mensagem de erro informará que a data e a hora especificadas são muito antigas.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date)},
ErrorMessage = "{0} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
Quando o valor especificado é uma data passada, a mensagem de erro personalizada é retornada.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.
Você pode aplicar formatação adicional na cadeia de caracteres com componentes de cadeia de caracteres de formato opcionais.
No exemplo a seguir, o valor do parâmetro EventDate deve ser maior ou igual à data e hora atuais. Se o valor for inválido, a mensagem de erro informará que a data especificada é muito antiga.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date).Date},
ErrorMessage = "{0:d} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
Quando o valor especificado é uma data passada, a mensagem de erro personalizada é retornada.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.
Atributo ValidateSet
O atributo ValidateSet especifica um conjunto de valores válidos para um parâmetro ou variável e habilita o preenchimento de tabulação. O PowerShell gerará 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 Detail só pode ser Low, Average ou High.
param(
[Parameter(Mandatory)]
[ValidateSet("Low", "Average", "High")]
[string[]]$Detail
)
No exemplo a seguir, o valor da variável $flavor deve ser Chocolate, Morango ou Baunilha.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"
A validação ocorre sempre que essa variável é atribuída mesmo dentro do script. Por exemplo, o seguinte resulta em um erro em tempo de execução:
param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
Este exemplo retorna o seguinte erro em tempo de execução:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Usando ValidateSet também habilitar a expansão de tabulação de valores para esse parâmetro. Para obter mais informações, consulte about_Tab_Expansion.
Valores Dynamic ValidateSet usando classes
Você pode usar uma classe para gerar dinamicamente os valores para ValidateSet em tempo de execução. No exemplo a seguir, os valores válidos para a variável $Sound são gerados por meio de uma classe chamada SoundNames que verifica três caminhos de sistema de arquivos para arquivos de som disponíveis:
Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
[string[]] GetValidValues() {
$SoundPaths = '/System/Library/Sounds/',
'/Library/Sounds','~/Library/Sounds'
$SoundNames = ForEach ($SoundPath in $SoundPaths) {
If (Test-Path $SoundPath) {
(Get-ChildItem $SoundPath).BaseName
}
}
return [string[]] $SoundNames
}
}
A [SoundNames] classe é então implementada como um valor ValidateSet dinâmico da seguinte maneira:
param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Observação
A IValidateSetValuesGenerator classe foi introduzida no PowerShell 6.0
Atributo de validação ValidateNotNull
O atributo ValidateNotNull especifica que o valor do parâmetro não pode ser $null. Quando o valor é $null, o PowerShell gera uma exceção.
O atributo ValidateNotNull foi projetado para ser usado quando o parâmetro é opcional e o tipo é indefinido ou tem um conversor de tipo que não pode converter implicitamente um valor nulo como objeto. Se você especificar um tipo que converte implicitamente um valor nulo, como uma cadeia de caracteres, o valor nulo será convertido em uma cadeia de caracteres vazia mesmo ao usar o atributo ValidateNotNull . Para esse cenário, use o atributo ValidateNotNullOrEmpty .
No exemplo a seguir, o valor do parâmetro ID não pode ser $null.
param(
[Parameter()]
[ValidateNotNull()]
$ID
)
Atributo de validação ValidateNotNullOrEmpty
O atributo ValidateNotNullOrEmpty especifica que o valor atribuído não pode ser nenhum dos seguintes valores:
$null- uma cadeia de caracteres vazia (
"") - uma matriz vazia (
@())
Quando o valor é inválido, o PowerShell gera uma exceção.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]$UserName
)
Atributo de validação ValidateDrive
O atributo ValidateDrive especifica que o valor do parâmetro deve representar o caminho, que se refere apenas às unidades permitidas. O PowerShell gerará um erro se o valor do parâmetro se referir a unidades diferentes das permitidas. A existência do caminho, exceto da unidade em si, não é verificada.
Se você usar o caminho relativo, a unidade atual deverá estar na lista de unidades permitidas.
param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
Atributo de validação ValidateUserDrive
O atributo ValidateUserDrive especifica que o valor do parâmetro deve representar na User unidade. O PowerShell gerará um erro se o caminho se referir a uma unidade diferente. O atributo validation testa apenas a existência do prefixo de unidade do caminho.
Se você usar o caminho relativo, a unidade atual deverá ser User.
function Test-UserDrivePath{
[OutputType([bool])]
param(
[Parameter(Mandatory, Position=0)]
[ValidateUserDrive()]
[string]$Path
)
$True
}
Test-UserDrivePath -Path C:\
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.
Você pode definir a User unidade em configurações de sessão Just Enough Administration (JEA). Para este exemplo, criamos a unidade User:.
New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH
Name Used (GB) Free (GB) Provider Root
---- --------- --------- -------- ----
User 75.76 24.24 FileSystem C:\Users\ExampleUser
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True
Atributo de validação ValidateTrustedData
Esse atributo foi adicionado no PowerShell 6.1.1.
No momento, o atributo é usado internamente pelo próprio PowerShell e não se destina ao uso externo.
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de