Nesta aula, vamos explorar um dos aspectos mais importantes da criação de funções no PowerShell: os parâmetros. Parâmetros permitem que você passe informações para suas funções, tornando-as mais flexíveis e reutilizáveis. Você aprenderá a usar o bloco param() para declarar parâmetros, como definir tipos específicos, valores padrão e a diferença entre parâmetros posicionais e nomeados.

Dominar parâmetros é essencial para escrever funções profissionais e robustas. Vamos começar com a estrutura básica e, em seguida, aprofundar em cada recurso.

param()

O bloco param() é a maneira padrão de declarar parâmetros em uma função no PowerShell. Ele deve ser colocado no início do corpo da função, antes de qualquer outro código. Dentro dos parênteses, você lista os parâmetros separados por vírgulas.

Exemplo básico:

function Saudacao {
    param(
        $Nome
    )
    Write-Host "Olá, $Nome!"
}

Saudacao -Nome "Maria"

No exemplo acima, a função Saudacao aceita um parâmetro chamado $Nome. Ao chamar a função, passamos o valor "Maria" usando a sintaxe -Nome "Maria". O PowerShell automaticamente associa o valor ao parâmetro.

Você também pode declarar vários parâmetros:

function Soma {
    param(
        $a,
        $b
    )
    return $a + $b
}

Soma -a 5 -b 3

O bloco param() é flexível e permite personalizar cada parâmetro com atributos adicionais, como veremos a seguir.

Tipagem

Por padrão, os parâmetros no PowerShell são do tipo object, o que significa que podem aceitar qualquer valor. No entanto, você pode restringir o tipo de dados que um parâmetro aceita, adicionando o tipo antes do nome do parâmetro. Isso ajuda a evitar erros e documenta melhor a função.

Exemplo com tipagem:

function Dividir {
    param(
        [int]$a,
        [int]$b
    )
    if ($b -eq 0) {
        Write-Error "Divisão por zero não permitida"
        return $null
    }
    return $a / $b
}

Dividir -a 10 -b 2   # Retorna 5
Dividir -a "10" -b 2  # Erro: não pode converter string para int

Nesse caso, os parâmetros $a e $b são tipados como [int]. Se você tentar passar uma string não numérica, o PowerShell lançará um erro. Tipos comuns incluem [string], [int], [double], [bool], [datetime], [array] e [hashtable].

Você também pode usar tipos mais complexos, como objetos personalizados ou classes. A tipagem torna suas funções mais previsíveis e seguras.

Valores padrão

Muitas vezes, você quer que um parâmetro tenha um valor padrão caso o usuário não o forneça. Isso é feito atribuindo um valor diretamente na declaração do parâmetro dentro do param().

Exemplo:

function SaudacaoPersonalizada {
    param(
        [string]$Nome,
        [string]$Saudacao = "Olá"
    )
    Write-Host "$Saudacao, $Nome!"
}

SaudacaoPersonalizada -Nome "João"           # Saída: Olá, João!
SaudacaoPersonalizada -Nome "João" -Saudacao "Oi"  # Saída: Oi, João!

No exemplo, o parâmetro $Saudacao tem valor padrão "Olá". Se o usuário não especificar um valor, ele assume o padrão. Se especificar, o valor fornecido substitui.

Valores padrão podem ser expressões, como (Get-Date).Year ou até mesmo $null. Eles são avaliados no momento em que a função é chamada, não quando é definida.

function MostrarData {
    param(
        [datetime]$Data = (Get-Date)
    )
    Write-Host "Data: $Data"
}

MostrarData                        # Mostra a data atual
MostrarData -Data "2024-12-25"     # Mostra 25/12/2024

Valores padrão são úteis para tornar parâmetros opcionais e fornecer um comportamento inteligente.

Parâmetros posicionais vs nomeados

No PowerShell, você pode passar argumentos para uma função de duas maneiras: posicionalmente (pela ordem) ou nomeadamente (usando o nome do parâmetro). Por padrão, os parâmetros são nomeados, mas você também pode usar a posição.

Parâmetros nomeados são explícitos e mais legíveis. Exemplo:

function Cadastro {
    param(
        [string]$Nome,
        [int]$Idade
    )
    Write-Host "Nome: $Nome, Idade: $Idade"
}

Cadastro -Nome "Ana" -Idade 30

Parâmetros posicionais são passados na ordem em que foram declarados. Exemplo:

Cadastro "Ana" 30   # Funciona, mas menos claro

Você pode controlar se um parâmetro aceita posição usando o atributo [Parameter(Position=0)]. Por exemplo:

function Cadastro {
    param(
        [Parameter(Position=0)]
        [string]$Nome,
        [Parameter(Position=1)]
        [int]$Idade
    )
    Write-Host "Nome: $Nome, Idade: $Idade"
}

Cadastro "Ana" 30   # Agora funciona posicionalmente

Se você não definir posições, os parâmetros podem ser usados tanto nomeados quanto posicionais, mas a ordem dos posicionais segue a declaração. É uma boa prática usar parâmetros nomeados para clareza, a menos que a ordem seja óbvia.

Você também pode misturar: os primeiros parâmetros podem ser posicionais e os demais nomeados.

Boas práticas

  • Sempre declare parâmetros com tipos apropriados para evitar erros.
  • Use valores padrão para parâmetros opcionais, em vez de verificar $null manualmente.
  • Prefira parâmetros nomeados em scripts públicos para melhor legibilidade.
  • Documente seus parâmetros com comentários baseados em ajuda (.PARAMETER).
  • Evite muitos parâmetros; considere usar um splatting ou hashtable para agrupar opções.

Referências

Exercícios

  1. Crie uma função chamada Multiplicar que aceite dois parâmetros tipados como [int] e retorne o produto. Teste com valores 4 e 5.

    ✓ Resposta: 
    function Multiplicar {
    param(
        [int]$a,
        [int]$b
    )
    return $a * $b
}

Multiplicar -a 4 -b 5   # Retorna 20
  2. Escreva uma função SaudacaoHora que aceite um parâmetro $Nome (string) e um parâmetro $Hora com valor padrão igual à hora atual (use (Get-Date).Hour). A função deve exibir "Bom dia", "Boa tarde" ou "Boa noite" dependendo da hora.

    ✓ Resposta: 
    function SaudacaoHora {
    param(
        [string]$Nome,
        [int]$Hora = (Get-Date).Hour
    )
    if ($Hora -lt 12) {
        $saudacao = "Bom dia"
    } elseif ($Hora -lt 18) {
        $saudacao = "Boa tarde"
    } else {
        $saudacao = "Boa noite"
    }
    Write-Host "$saudacao, $Nome!"
}

SaudacaoHora -Nome "Carlos"
  3. Crie uma função InfoPessoa que aceite parâmetros $Nome (string) e $Idade (int). Use o atributo [Parameter(Position=0)] e [Parameter(Position=1)] para que possam ser passados posicionalmente. Teste chamando com argumentos posicionais.

    ✓ Resposta: 
    function InfoPessoa {
    param(
        [Parameter(Position=0)]
        [string]$Nome,
        [Parameter(Position=1)]
        [int]$Idade
    )
    Write-Host "$Nome tem $Idade anos."
}

InfoPessoa "Maria" 28
  4. Escreva uma função Calcular que aceite três parâmetros: $a (int), $b (int) e $Operacao (string) com valor padrão "soma". Se $Operacao for "soma", retorne a soma; se for "subtracao", retorne a subtração; caso contrário, retorne 0.

    ✓ Resposta: 
    function Calcular {
    param(
        [int]$a,
        [int]$b,
        [string]$Operacao = "soma"
    )
    switch ($Operacao) {
        "soma" { return $a + $b }
        "subtracao" { return $a - $b }
        default { return 0 }
    }
}

Calcular -a 10 -b 5 -Operacao "subtracao"   # Retorna 5
Calcular -a 10 -b 5                         # Retorna 15 (soma)
  5. Crie uma função ListarArquivos que aceite um parâmetro $Caminho (string) com valor padrão "C:\" e um parâmetro $Extensao (string) com valor padrão "*.*". A função deve listar os arquivos no caminho especificado que correspondem à extensão. Use Get-ChildItem.

    ✓ Resposta: 
    function ListarArquivos {
    param(
        [string]$Caminho = "C:\",
        [string]$Extensao = "*.*"
    )
    Get-ChildItem -Path $Caminho -Filter $Extensao -File
}

ListarArquivos -Caminho "C:\Windows" -Extensao "*.txt"