Compartilhar via

about_Functions_Advanced_Parameters

  • Artigo

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 da função enviam com o parâmetro.

Quando você usa o atributo, o CmdletBinding PowerShell adiciona automaticamente os Parâmetros Comuns. Você não pode criar parâmetros que usem os mesmos nomes que os Parâmetros comuns. Para obter mais informações, confira about_CommonParameters.

A partir do PowerShell 3.0, você pode usar splatting with @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 no tipo de destino do parâmetro. As funções avançadas executam a análise invariável de cultura de valores de parâmetro.

Por outro lado, uma conversão que diferencia a cultura é executada durante a associaçã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

Conforme mostrado acima, os cmdlets usam a 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 invariável de cultura, o que resulta no erro a seguir.

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 informações do pipeline.
  • Ele usa uma matriz de strings como entrada.
param(
    [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
    [string[]]$ComputerName
)

Parâmetros de opção

Os parâmetros de comutação são parâmetros que não recebem nenhum valor de parâmetro. Em vez disso, eles transmitem um valor booleano verdadeiro ou falso por meio de sua presença ou ausência, de modo que, quando um parâmetro switch está presente, ele tem um valor verdadeiro e, quando ausente, tem um valor falso .

Por exemplo, o parâmetro Recurse of Get-ChildItem é um parâmetro switch.

Para criar um parâmetro switch em uma função, especifique o switch tipo na definição do 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 alternância são fáceis de usar e são preferidos em relação aos parâmetros boolianos, 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 booliano.

-IncludeAll $true

Ao criar parâmetros de switch, escolha o nome do parâmetro com cuidado. Certifique-se de que o nome do parâmetro comunique o efeito do parâmetro ao usuário. Evite termos ambíguos, como Filtro ou Máximo , que podem implicar que um valor é necessário.

Considerações sobre o design do parâmetro do switch

  • Os parâmetros Switch não devem receber valores padrão. Eles devem sempre ser falsos por padrão.

  • 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 switch não são. Você pode substituir isso no atributo Parâmetro, mas isso confundirá os usuários.

  • Os parâmetros de switch 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 switch.

  • Os parâmetros de comutação não devem ser obrigatórios. O único caso em que é necessário tornar um parâmetro switch obrigatório é quando ele é necessário para diferenciar um conjunto de parâmetros.

  • A configuração explícita de uma opção de um booleano pode ser feita com -MySwitch:$boolValue e em splatting com $params = @{ MySwitch = $boolValue }.

  • Os parâmetros Switch são do tipo SwitchParameter, que converte implicitamente 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 de função ou quando outro parâmetro tem um determinado valor.

Os parâmetros dinâmicos podem ser úteis, mas use-os apenas quando necessário, pois 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 HKEY_LOCAL_MACHINE unidade do 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 reconhecida 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 da 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 incluem o argumento e seu valor devem seguir Parameter sem espaço intermediário.

param(
    [Parameter(Argument=value)]
    $ParameterName
)

Use vírgulas para separar os 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 são padronizados como False quando omitidos do atributo Parameter . Defina o valor do argumento como $true ou apenas liste o argumento pelo nome. Por exemplo, os seguintes atributos de parâmetro 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 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 número 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 você 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 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 do objeto 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 obrigatório e aceita a entrada da propriedade ComputerName do objeto que é passada para a função por meio 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 a entrada de pipeline (by Value) ou (by PropertyName) permite o uso de blocos de script de associação de atraso no parâmetro.

O bloco de script delay-bind é executado automaticamente durante ParameterBinding. O resultado é associado ao parâmetro. A associaçã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 associaçã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 estão atribuídos a outros parâmetros da função.

O exemplo a seguir declara um parâmetro Value obrigatório e um parâmetro Remaining que aceita todos os valores de parâmetro restantes enviados à 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 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 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 os 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 obrigatório ComputerName .

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 pelo Get-Help 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 do 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 de 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 pelo Get-Help 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

Você não pode 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 têm mais suporte. 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 tem um parâmetro de opção NoTypeInformation que controla se as informações de tipo sã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 interromper os 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 dá 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 lidar com 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 preenchimento de tabulação a um parâmetro específico. Um atributo ArgumentCompletions deve ser definido para cada parâmetro que precisa de preenchimento 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 preenchimento de tabulação a um parâmetro específico. Um atributo ArgumentCompleter deve ser definido para cada parâmetro que precisa de preenchimento de tabulação. Assim 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 só é aplicada à 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 a validação para qualquer variável dentro de um script.

Observação

Ao usar qualquer atributo com uma variável tipada, é 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 de validação inesperadas.

[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 da tabela de hash 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 cadeia de caracteres, 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 usa 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 parâmetro ou valor de 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 de comprimento 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 parâmetro ou ao valor 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 enumeração ValidateRangeKind para cada parâmetro ou valor de variável. O PowerShell gerará um erro se algum valor estiver fora desse intervalo.

A enumeração ValidateRangeKind permite os seguintes valores:

  • Positive - Um número maior que zero.
  • Negative - Um número menor que zero.
  • NonPositive - Um número menor ou igual a zero.
  • NonNegative - 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 gerar 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 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(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 string com componentes de string 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 permite 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 no 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 dinâmicos de 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 do 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 classe é então implementada [SoundNames] como um valor dinâmico ValidateSet 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 converta 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 string vazia ("")
  • uma matriz vazia (@())

Quando o valor é inválido, o PowerShell gera uma exceção.

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string[]]$UserName
)

ValidateNotNullOrWhiteSpace atributo de validação

O atributo ValidateNotNullOrWhiteSpace especifica que o valor atribuído não pode ser nenhum dos seguintes valores:

  • $null
  • uma string vazia ("")
  • uma matriz vazia @()
  • uma cadeia de caracteres que contém apenas caracteres de espaço em branco, como tabulações, espaços, retornos de carro e novas linhas
  • uma matriz que contém todas as strings vazias ou contém apenas caracteres de espaço em branco

Quando o valor é inválido, o PowerShell gera uma exceção.

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrWhiteSpace()]
    [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 a 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 para a 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 ser representado na User unidade. O PowerShell gerará um erro se o caminho se referir a uma unidade diferente. O atributo de validação testa apenas a existência do prefixo de unidade do caminho.

Se você usar o caminho relativo, a unidade atual deve 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 User a 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