Em scripts e funções do PowerShell, a validação de parâmetros é essencial para evitar erros em tempo de execução. Em vez de escrever código manual para verificar cada argumento, você pode usar atributos de validação que são aplicados diretamente aos parâmetros. Esses atributos são processados automaticamente pelo PowerShell antes de executar o corpo da função, garantindo que os valores fornecidos estejam dentro das regras definidas.

Nesta aula, exploraremos quatro atributos fundamentais: [ValidateNotNull], [ValidateSet], [ValidatePattern] e [ValidateRange]. Cada um deles resolve um problema comum de validação, como garantir que um parâmetro não seja nulo, que esteja em uma lista de valores permitidos, que corresponda a um padrão de expressão regular ou que esteja dentro de um intervalo numérico. Vamos ver exemplos práticos de cada um.

[ValidateNotNull]

O atributo [ValidateNotNull] garante que o valor passado para o parâmetro não seja $null. Se o usuário tentar passar $null ou omitir o parâmetro (quando ele não é opcional), o PowerShell lançará um erro antes de executar a função. Isso é útil para parâmetros obrigatórios que não podem ser nulos, como objetos, strings ou coleções.

É importante notar que [ValidateNotNull] não impede strings vazias ('') ou valores como 0 ou $false. Para validar strings não vazias, você pode combinar com [ValidateNotNullOrEmpty]. Exemplo:

function Get-UserInfo {
    param(
        [Parameter(Mandatory)]
        [ValidateNotNull()]
        [string]$UserName
    )
    Write-Host "Consultando informações de $UserName"
}

# Isso funciona:
Get-UserInfo -UserName "Joao"

# Isso gera erro (nulo):
Get-UserInfo -UserName $null

[ValidateSet]

O atributo [ValidateSet] restringe o valor do parâmetro a um conjunto específico de valores permitidos. Se o usuário fornecer um valor que não está na lista, o PowerShell exibe um erro com as opções válidas. Esse atributo é ideal para parâmetros que aceitam apenas opções predefinidas, como níveis de log, modos de operação ou cores.

O PowerShell também oferece autocompletar (tab completion) para parâmetros com [ValidateSet], facilitando o uso. Exemplo:

function Set-LogLevel {
    param(
        [ValidateSet('Info', 'Warning', 'Error')]
        [string]$Level
    )
    Write-Host "Nível de log definido para: $Level"
}

# Válido:
Set-LogLevel -Level 'Warning'

# Inválido (gera erro):
Set-LogLevel -Level 'Debug'

[ValidatePattern]

O atributo [ValidatePattern] usa uma expressão regular para validar o valor do parâmetro. Se o valor não corresponder ao padrão, um erro é gerado. Isso é útil para formatos específicos, como endereços de e-mail, números de telefone, IDs ou códigos.

A expressão regular é fornecida como uma string e pode incluir opções como IgnoreCase (ignorar maiúsculas/minúsculas). Exemplo:

function Validate-Email {
    param(
        [ValidatePattern('^[\w.-]+@[\w.-]+\.\w+$')]
        [string]$Email
    )
    Write-Host "E-mail válido: $Email"
}

# Válido:
Validate-Email -Email 'usuario@exemplo.com'

# Inválido:
Validate-Email -Email 'invalido'

[ValidateRange]

O atributo [ValidateRange] verifica se o valor numérico do parâmetro está dentro de um intervalo especificado (incluindo os limites). Você define os valores mínimo e máximo. Se o valor estiver fora do intervalo, o PowerShell gera um erro. Esse atributo funciona com tipos numéricos como [int], [double], [long], etc.

Exemplo:

function Set-Temperature {
    param(
        [ValidateRange(-10, 50)]
        [int]$Celsius
    )
    Write-Host "Temperatura definida para $Celsius °C"
}

# Válido:
Set-Temperature -Celsius 25

# Inválido (fora do intervalo):
Set-Temperature -Celsius 100

Boas práticas e observações finais

Ao usar atributos de validação, lembre-se de que eles são executados antes do corpo da função, então você pode confiar que os parâmetros estão dentro das regras. Combine múltiplos atributos quando necessário (por exemplo, [ValidateNotNull()] com [ValidateSet()]). Para validações mais complexas, considere usar [ValidateScript()] que permite um bloco de script personalizado. Sempre documente os valores esperados nos comentários da função para ajudar outros desenvolvedores.

Referências

Exercícios

  1. Crie uma função chamada New-User que tenha um parâmetro Name obrigatório e que não aceite nulo. Use [ValidateNotNull]. Teste com $null e veja o erro.

    ✓ Resposta: 
    function New-User {
    param(
        [Parameter(Mandatory)]
        [ValidateNotNull()]
        [string]$Name
    )
    Write-Host "Criando usuário: $Name"
}

# Teste:
New-User -Name $null  # Gera erro: Cannot validate argument on parameter 'Name'. The argument is null or empty.
  2. Escreva uma função Set-Color que aceite apenas as cores 'Red', 'Green' ou 'Blue' usando [ValidateSet]. Teste com 'Yellow'.

    ✓ Resposta: 
    function Set-Color {
    param(
        [ValidateSet('Red', 'Green', 'Blue')]
        [string]$Color
    )
    Write-Host "Cor definida: $Color"
}

# Teste:
Set-Color -Color 'Yellow'  # Gera erro: Cannot validate argument on parameter 'Color'... The argument "Yellow" does not belong to the set "Red,Green,Blue".
  3. Implemente uma função Validate-Phone que valide um número de telefone no formato (XX) XXXXX-XXXX usando [ValidatePattern]. Use a expressão regular ^\(\d{2}\) \d{5}-\d{4}$. Teste com um número válido e um inválido.

    ✓ Resposta: 
    function Validate-Phone {
    param(
        [ValidatePattern('^\(\d{2}\) \d{5}-\d{4}$')]
        [string]$Phone
    )
    Write-Host "Telefone válido: $Phone"
}

# Teste:
Validate-Phone -Phone '(11) 91234-5678'  # Válido
Validate-Phone -Phone '12345'            # Inválido (erro)
  4. Crie uma função Set-Age que aceite apenas idades entre 0 e 120 usando [ValidateRange]. Teste com 150.

    ✓ Resposta: 
    function Set-Age {
    param(
        [ValidateRange(0, 120)]
        [int]$Age
    )
    Write-Host "Idade definida: $Age"
}

# Teste:
Set-Age -Age 150  # Gera erro: Cannot validate argument on parameter 'Age'... The argument 150 is greater than the maximum allowed range of 120.
  5. Combine [ValidateNotNull()] e [ValidateSet()] em um parâmetro Mode de uma função Set-Mode. O parâmetro deve ser obrigatório, não nulo e aceitar apenas 'Fast', 'Normal' ou 'Slow'. Teste com $null e com 'Medium'.

    ✓ Resposta: 
    function Set-Mode {
    param(
        [Parameter(Mandatory)]
        [ValidateNotNull()]
        [ValidateSet('Fast', 'Normal', 'Slow')]
        [string]$Mode
    )
    Write-Host "Modo definido: $Mode"
}

# Teste:
Set-Mode -Mode $null   # Erro: ValidateNotNull
Set-Mode -Mode 'Medium' # Erro: ValidateSet