Atributos de parâmetros avançados

Em funções PowerShell avançadas, você pode decorar parâmetros com atributos para controlar seu comportamento, validação e interação com o usuário. Esses atributos são definidos dentro de colchetes antes da declaração do parâmetro e permitem criar scripts mais robustos e intuitivos. Nesta aula, exploraremos quatro atributos essenciais: [Parameter(Mandatory)], Parameter Sets, Switch parameters e Aliases.

Compreender esses atributos é fundamental para construir funções que se comportam como cmdlets nativos, oferecendo prompts automáticos para parâmetros obrigatórios, evitando ambiguidades com conjuntos de parâmetros e simplificando a digitação com aliases. Vamos mergulhar em cada um deles com exemplos práticos.

[Parameter(Mandatory)]

O atributo [Parameter(Mandatory)] torna um parâmetro obrigatório. Se o usuário não fornecer um valor, o PowerShell solicitará interativamente o valor (a menos que a função seja chamada com $PSBoundParameters ou em modo não interativo). Isso evita que a função prossiga sem dados essenciais.

Por exemplo, uma função que cria um arquivo de log precisa do nome do arquivo. Usamos [Parameter(Mandatory=$true)] (ou simplesmente [Parameter(Mandatory)]). O PowerShell automaticamente exibirá um prompt pedindo o valor se ele não for fornecido.

function New-LogFile {
    param(
        [Parameter(Mandatory)]
        [string]$LogName
    )
    "Creating log file: $LogName"
}

# Chamada sem o parâmetro: o PowerShell pedirá o valor
New-LogFile

Você também pode personalizar a mensagem de prompt com HelpMessage: [Parameter(Mandatory, HelpMessage='Enter the log file name')]. Isso melhora a experiência do usuário.

Parameter Sets

Parameter Sets permitem que uma função tenha diferentes conjuntos de parâmetros que são mutuamente exclusivos. Por exemplo, um cmdlet pode aceitar um nome de computador ou um arquivo de entrada, mas não ambos ao mesmo tempo. Cada conjunto é identificado por um nome e pode ter parâmetros exclusivos ou compartilhados.

Para definir um parameter set, use [Parameter(ParameterSetName='NomeDoSet')]. Um parâmetro pode pertencer a múltiplos sets. O PowerShell seleciona automaticamente o set correto com base nos parâmetros fornecidos.

function Get-Data {
    param(
        [Parameter(ParameterSetName='Computer', Mandatory)]
        [string]$ComputerName,
        [Parameter(ParameterSetName='File', Mandatory)]
        [string]$FilePath,
        [Parameter(ParameterSetName='Computer')]
        [PSCredential]$Credential
    )
    if ($PSCmdlet.ParameterSetName -eq 'Computer') {
        "Connecting to $ComputerName"
    } else {
        "Reading from $FilePath"
    }
}

Note que $Credential só é válido no set 'Computer'. Se você tentar usar -FilePath e -Credential juntos, o PowerShell gerará um erro. Use $PSCmdlet.ParameterSetName para saber qual set foi ativado.

Switch Parameters

Switch parameters são parâmetros booleanos que não exigem um valor explícito. Eles são usados para flags, como -Verbose ou -Force. No PowerShell, declara-se um switch com o tipo [switch]. Se o parâmetro for passado, seu valor será $true; caso contrário, $false.

Diferente de [bool], um switch não precisa de $true ou $false após o nome. Apenas a presença do argumento já o torna verdadeiro.

function Remove-ItemSafely {
    param(
        [string]$Path,
        [switch]$Recurse
    )
    if ($Recurse) {
        "Removing $Path recursively"
    } else {
        "Removing $Path"
    }
}

Remove-ItemSafely -Path "C:\temp" -Recurse

Você também pode usar [switch]$Force e combiná-lo com outros parâmetros. Switch parameters são ideais para opções que ativam ou desativam comportamentos.

Aliases

Aliases (ou apelidos) permitem que um parâmetro seja referenciado por nomes alternativos. Por exemplo, o cmdlet Get-ChildItem aceita o alias dir para o parâmetro -Path. Para definir um alias em uma função, use o atributo [Alias()] antes do parâmetro.

Isso é útil para compatibilidade com cmdlets existentes ou para abreviar nomes longos.

function Get-MyProcess {
    param(
        [Alias('Name', 'ProcName')]
        [string]$ProcessName
    )
    Get-Process -Name $ProcessName
}

# Agora você pode usar:
Get-MyProcess -ProcessName "powershell"
Get-MyProcess -Name "powershell"
Get-MyProcess -ProcName "powershell"

Você pode definir múltiplos aliases separando-os por vírgulas. Lembre-se de que aliases são case-insensitive e não devem conflitar com outros parâmetros.

Boas Práticas

Ao usar esses atributos, mantenha a consistência com os cmdlets nativos. Use Mandatory apenas quando o parâmetro for essencial. Parameter sets devem ser projetados para evitar ambiguidades. Switch parameters são preferíveis a [bool] para flags. E aliases devem ser intuitivos e não poluir o namespace.

Referências

• About Functions Advanced Parameters - Microsoft Docs
• About Parameter Sets - Microsoft Docs
• About Switch - Microsoft Docs
• About Aliases - Microsoft Docs
• Everything You Wanted to Know About Parameters - Microsoft Docs

Exercícios

1. Crie uma função chamada Set-Configuration que tenha um parâmetro obrigatório -ConfigFile do tipo string e um switch -Force. A função deve exibir o nome do arquivo e se o modo Force está ativo.

Ver resposta

✓ Resposta:

function Set-Configuration {
    param(
        [Parameter(Mandatory)]
        [string]$ConfigFile,
        [switch]$Force
    )
    if ($Force) {
        "Forcing configuration on $ConfigFile"
    } else {
        "Setting configuration on $ConfigFile"
    }
}

2. Modifique a função anterior para que ela aceite o parâmetro -ConfigFile também com o alias -File.

Ver resposta

✓ Resposta:

function Set-Configuration {
    param(
        [Parameter(Mandatory)]
        [Alias('File')]
        [string]$ConfigFile,
        [switch]$Force
    )
    if ($Force) {
        "Forcing configuration on $ConfigFile"
    } else {
        "Setting configuration on $ConfigFile"
    }
}

3. Crie uma função Get-UserInfo com dois parameter sets: 'ByUserName' (com parâmetro obrigatório -UserName) e 'ByID' (com parâmetro obrigatório -UserID). A função deve exibir qual set foi usado.

Ver resposta

✓ Resposta:

function Get-UserInfo {
    param(
        [Parameter(ParameterSetName='ByUserName', Mandatory)]
        [string]$UserName,
        [Parameter(ParameterSetName='ByID', Mandatory)]
        [int]$UserID
    )
    if ($PSCmdlet.ParameterSetName -eq 'ByUserName') {
        "Getting user by name: $UserName"
    } else {
        "Getting user by ID: $UserID"
    }
}

4. Adicione um parâmetro opcional -Department ao set 'ByUserName' da função anterior.

Ver resposta

✓ Resposta:

function Get-UserInfo {
    param(
        [Parameter(ParameterSetName='ByUserName', Mandatory)]
        [string]$UserName,
        [Parameter(ParameterSetName='ByID', Mandatory)]
        [int]$UserID,
        [Parameter(ParameterSetName='ByUserName')]
        [string]$Department
    )
    if ($PSCmdlet.ParameterSetName -eq 'ByUserName') {
        $msg = "Getting user by name: $UserName"
        if ($Department) { $msg += " in department $Department" }
        $msg
    } else {
        "Getting user by ID: $UserID"
    }
}

5. Escreva uma função Invoke-Test que tenha um switch -Verbose e um parâmetro obrigatório -TestName com alias -Name. A função deve exibir o nome do teste e, se -Verbose for usado, exibir detalhes adicionais.

Ver resposta

✓ Resposta:

function Invoke-Test {
    param(
        [Parameter(Mandatory)]
        [Alias('Name')]
        [string]$TestName,
        [switch]$Verbose
    )
    if ($Verbose) {
        "Running test $TestName with verbose output"
    } else {
        "Running test $TestName"
    }
}