Atributos de parâmetros avançados

Em funções avançadas do PowerShell, os parâmetros podem ser decorados com atributos que controlam seu comportamento. O atributo [Parameter()] é o principal mecanismo para definir propriedades como obrigatoriedade, posição, valor padrão e agrupamento em conjuntos. Nesta aula, exploraremos quatro aspectos essenciais: parâmetros obrigatórios (Mandatory), conjuntos de parâmetros (Parameter Sets), parâmetros do tipo switch e aliases (apelidos).

Compreender esses conceitos é fundamental para criar funções robustas e intuitivas, que se comportam de forma previsível e são fáceis de usar tanto na linha de comando quanto em scripts.

[Parameter(Mandatory)]

O atributo [Parameter(Mandatory = $true)] torna um parâmetro obrigatório. Se o usuário não fornecer um valor para esse parâmetro, o PowerShell solicitará o valor interativamente (a menos que o pipeline esteja sendo usado para fornecer o valor).

Exemplo de função com parâmetro obrigatório:

function Get-UserInfo {
    param(
        [Parameter(Mandatory = $true)]
        [string]$UserName
    )
    Write-Host "Obtendo informações para o usuário: $UserName"
}

Se você chamar Get-UserInfo sem o parâmetro -UserName, o PowerShell exibirá uma solicitação para digitar o valor. Para evitar a solicitação, você pode fornecer o valor via pipeline ou usar o parâmetro -ErrorAction Stop para gerar um erro.

Parameter Sets

Parameter Sets (conjuntos de parâmetros) permitem que uma função tenha diferentes combinações de parâmetros que são mutuamente exclusivas. Cada conjunto é identificado por um nome e pode conter parâmetros opcionais ou obrigatórios. O PowerShell seleciona automaticamente o conjunto correto com base nos parâmetros fornecidos.

Sintaxe básica:

function Set-Config {
    param(
        [Parameter(ParameterSetName = 'Path', Mandatory = $true)]
        [string]$ConfigPath,
        [Parameter(ParameterSetName = 'Name', Mandatory = $true)]
        [string]$ConfigName,
        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'Name')]
        [switch]$Force
    )
    if ($PSCmdlet.ParameterSetName -eq 'Path') {
        Write-Host "Usando caminho: $ConfigPath"
    } else {
        Write-Host "Usando nome: $ConfigName"
    }
}

Exemplo de uso: Set-Config -ConfigPath "C:\config.ini" ou Set-Config -ConfigName "default". Não é possível usar ambos simultaneamente. O parâmetro -Force está disponível em ambos os conjuntos.

Switch Parameters

Parâmetros do tipo [switch] são usados para representar flags booleanas. Eles não aceitam um valor; sua presença indica $true e ausência indica $false. São ideais para ativar/desativar comportamentos.

Exemplo:

function Invoke-Task {
    param(
        [switch]$Verbose
    )
    if ($Verbose) {
        Write-Host "Executando com detalhes..."
    }
    # resto da lógica
}

Uso: Invoke-Task -Verbose ativa a saída detalhada. Sem a chave, a condição é falsa. Parâmetros switch também podem ser usados em parameter sets para diferenciar comportamentos.

Aliases

Aliases (apelidos) para parâmetros permitem que o usuário use nomes mais curtos ou alternativos. Eles são definidos com o atributo [Alias()] dentro do bloco param().

Exemplo:

function Remove-ItemSafely {
    param(
        [Parameter(Mandatory = $true)]
        [Alias('Path', 'FullName')]
        [string]$ItemPath
    )
    Write-Host "Removendo $ItemPath"
}

O parâmetro -ItemPath pode ser chamado como -Path ou -FullName. Múltiplos aliases são separados por vírgula. Aliases são úteis para compatibilidade com nomes de cmdlets existentes ou para abreviações.

Boas Práticas

• Sempre documente os parâmetros com comentários baseados em ajuda (.PARAMETER) para melhorar a experiência do usuário.
• Use nomes de parâmetros descritivos e consistentes com os padrões do PowerShell (substantivo-verbo).
• Evite criar muitos parameter sets; prefira funções separadas se a lógica for muito diferente.
• Para switches, evite usar $true ou $false como valor; simplesmente presença/ausência é suficiente.
• Aliases devem ser curtos e intuitivos, mas não substituem a documentação adequada.

Referências

• About Functions Advanced Parameters
• About Parameter Sets
• About Switch
• About Aliases
• Strongly Encouraged Development Guidelines

Exercícios

1. Crie uma função chamada New-User que tenha um parâmetro obrigatório -UserName do tipo string. Teste chamar a função sem o parâmetro e veja o que acontece.

   Ver resposta

   ✓ Resposta:

   function New-User {
       param(
           [Parameter(Mandatory = $true)]
           [string]$UserName
       )
       Write-Host "Criando usuário: $UserName"
   }

   Ao chamar New-User sem argumentos, o PowerShell solicitará o valor de UserName.

2. Modifique a função New-User para incluir um parameter set chamado 'WithEmail' que exija um parâmetro -Email e outro conjunto chamado 'WithoutEmail' que não exija email. O parâmetro -UserName deve ser comum a ambos.

   Ver resposta

   ✓ Resposta:

   function New-User {
       param(
           [Parameter(Mandatory = $true)]
           [string]$UserName,
           [Parameter(ParameterSetName = 'WithEmail', Mandatory = $true)]
           [string]$Email
       )
       if ($PSCmdlet.ParameterSetName -eq 'WithEmail') {
           Write-Host "Criando usuário $UserName com email $Email"
       } else {
           Write-Host "Criando usuário $UserName sem email"
       }
   }

3. Adicione um parâmetro switch chamado -Force à função do exercício anterior, que esteja disponível em ambos os parameter sets.

   Ver resposta

   ✓ Resposta:

   function New-User {
       param(
           [Parameter(Mandatory = $true)]
           [string]$UserName,
           [Parameter(ParameterSetName = 'WithEmail', Mandatory = $true)]
           [string]$Email,
           [Parameter(ParameterSetName = 'WithEmail')]
           [Parameter(ParameterSetName = 'WithoutEmail')]
           [switch]$Force
       )
       if ($Force) {
           Write-Host "Forçando criação..."
       }
       if ($PSCmdlet.ParameterSetName -eq 'WithEmail') {
           Write-Host "Criando usuário $UserName com email $Email"
       } else {
           Write-Host "Criando usuário $UserName sem email"
       }
   }

4. Crie uma função chamada Get-ProcessInfo que aceite um parâmetro -ProcessName com um alias -Name. O parâmetro deve ser obrigatório. Teste chamar a função com -Name.

   Ver resposta

   ✓ Resposta:

   function Get-ProcessInfo {
       param(
           [Parameter(Mandatory = $true)]
           [Alias('Name')]
           [string]$ProcessName
       )
       Get-Process -Name $ProcessName
   }

   Chamada: Get-ProcessInfo -Name "powershell" funciona normalmente.

5. Combine todos os conceitos: crie uma função Set-Environment que tenha dois parameter sets: 'Variable' (com parâmetros obrigatórios -Name e -Value) e 'File' (com parâmetro obrigatório -Path). Adicione um switch -Global disponível em ambos os sets e um alias -EnvName para o parâmetro -Name.

   Ver resposta

   ✓ Resposta:

   function Set-Environment {
       param(
           [Parameter(ParameterSetName = 'Variable', Mandatory = $true)]
           [Alias('EnvName')]
           [string]$Name,
           [Parameter(ParameterSetName = 'Variable', Mandatory = $true)]
           [string]$Value,
           [Parameter(ParameterSetName = 'File', Mandatory = $true)]
           [string]$Path,
           [Parameter(ParameterSetName = 'Variable')]
           [Parameter(ParameterSetName = 'File')]
           [switch]$Global
       )
       if ($PSCmdlet.ParameterSetName -eq 'Variable') {
           if ($Global) { [Environment]::SetEnvironmentVariable($Name, $Value, 'Machine') }
           else { [Environment]::SetEnvironmentVariable($Name, $Value, 'User') }
           Write-Host "Variável $Name definida como $Value"
       } else {
           Write-Host "Carregando ambiente do arquivo: $Path"
           # Lógica para carregar variáveis do arquivo
       }
   }