Parâmetros de Função PowerShell

1. Definindo Parâmetros de Função PowerShell
2. Parâmetros Nomeados na Função PowerShell
3. Parâmetros Posicionais na Função PowerShell
4. Parâmetros de Alternância na Função PowerShell
5. Splatting em Parâmetros de Função PowerShell
6. Atributos de Parâmetro PowerShell
7. Função Avançada Com Sintaxe de Parâmetro Nomeado

Os parâmetros da função PowerShell tornam as funções mais poderosas ao alavancar características e argumentos para limitar os usuários de inserir valores específicos. Ele adiciona algumas regras e validações para evitar a necessidade de escrever scripts extensos, e são simples de usar.

Os argumentos também podem ser dados via linha de comando uma vez que os parâmetros da função tenham sido especificados. Parâmetros nomeados, posicionais, de alternância e dinâmicos são todos exemplos de parâmetros de função. Os parâmetros de função também podem ser usados para transformar uma função básica em uma mais complexa.

Definindo Parâmetros de Função PowerShell

Os parâmetros são definidos da seguinte forma.

param(
    $Parameter1
)

As melhores práticas recomendam adicionar um tipo ao parâmetro e inserir um bloco Parameter() para garantir que o parâmetro aceite apenas o tipo de entrada que você precisa e permitirá mais recursos no futuro. Portanto, é feito da maneira mostrada abaixo.

param(
    [Parameter()]
    [string]$Parameter1
)

Até parâmetros adicionais podem ser adicionados à sintaxe acima, como mostrado abaixo.

param(
    [Parameter()]
    [string]$Param1,
 
    [Parameter()]
    [string]$Param2
)
 
Write-Host "Param1 value is $Param1"
Write-Host "Param 2 value is $Param2"

Parâmetros Nomeados na Função PowerShell

Parâmetros nomeados são uma técnica para usar parâmetros de função PowerShell dentro de um script. Use o nome completo do argumento ao invocar um script ou função com parâmetros nomeados.

Vamos supor que o script PowerShell acima está armazenado em test.ps1. Aqui estaremos fornecendo valores para param1 e param2; você pode notar no exemplo abaixo que o nome completo do parâmetro deve ser passado.

./test.ps1 -Param1 'value' -Param2 'valuenext'

Saída:

Quando você executar esse script, verá algo assim, onde cada variável de argumento é substituída pelo valor fornecido em tempo de execução.

Parâmetros Posicionais na Função PowerShell

Passar itens por posição em vez de nome é outra maneira de utilizar parâmetros. O nome do parâmetro não é utilizado ao passar um valor de parâmetro por posição. Em vez disso, o PowerShell compara os valores de cada argumento com sua localização na função. O PowerShell reconhece que Param1 foi especificado antes de Param2 no código e combina os valores na sequência correta.

./test.ps1 'value' 'valuenext'

Saída

Param1 value value
Param 2 value is valuenext

Tanto param1 quanto param2 foram declarados como tipos de string no exemplo acima, mas não é o único tipo que você pode usar. Qualquer tipo da biblioteca de classes .NET pode ser utilizado.

Além da ordem original, também podemos avançar dando a posição dentro da construção do parâmetro também. Isso é mostrado abaixo.

param(
    [Parameter(position = 1)]
    [string]$Param1,
 
    [Parameter(position = 0)]
    [string]$Param2
)
 
Write-Host "Param1 value is $Param1"
Write-Host "Param 2 value is $Param2"

Aqui, você pode ver que a ordem dos parâmetros foi alterada.

./test.ps1 'param2' 'param1'

Parâmetros de Alternância na Função PowerShell

Este parâmetro é usado para sinalizar se algo está ligado ou desligado usando valores binários ou booleanos. O tipo switch é usado para especificá-lo. Continuando com o exemplo acima, adicionaremos outro parâmetro de alternância chamado DisplayParam2.

param(
    [Parameter()]
    [string]$Param1,
 
    [Parameter()]
    [string]$Param2,
 
    [Parameter()]
    [switch]$DisplayParam2
)
 
Write-Host "Param1 value is $Param1"
if ($DisplayParam2.IsPresent) {
    Write-Host "Param2 value is $Param2"
}

Saída:

Splatting em Parâmetros de Função PowerShell

Splatting é usado principalmente quando há muitos parâmetros. Configurar parâmetros para um script antes de executar um comando é referido como splatting. Você tem definido e passado valores para parâmetros em tempo de execução até agora. Uma vez que você tem uma coleção de parâmetros que aparecem abaixo, isso pode ser um problema.

param(
    [Parameter()]
    [string]$Param1,
 
    [Parameter()]
    [string]$Param2,
 
    [Parameter()]
    [switch]$DisplayParam2,
 
    [Parameter()]
    [string]$Param3,
 
    [Parameter()]
    [string]$Param4,
 
    [Parameter()]
    [string]$Param5,
 
    [Parameter()]
    [string]$Param6,
 
    [Parameter()]
    [string]$Param7
)
 
Write-Host "Param1 value is $Param1"
if ($DisplayParam2.IsPresent) {
    Write-Host "Param2 value is $Param2"
}
Write-Host "Param3 value is $Param3"
Write-Host "Param4 value is $Param4"
Write-Host "Param5 value is $Param5"
Write-Host "Param6 value is $Param6"
Write-Host "Param7 value is $Param7"

Em vez de deslizar para a direita, você pode usar um hashtable para especificar os valores dos parâmetros em uma fase separada, como ilustrado abaixo. Os valores dos parâmetros podem ser organizados de forma ordenada, facilitando muito entender quais estão em uso.

Uma vez que o hashtable é estabelecido, você pode especificar o nome do hashtable seguido por um caractere @ para enviar todos os argumentos para o script.

$params = @{
    Param1        = 'value'
    Param2        = 'valuenext'
    Param3        = 'somevalue'
    Param4        = 'somevalue'
    Param5        = 'somevalue'
    Param6        = 'somevalue'
    Param7        = 'somevalue'
    DisplayParam2 = $true
}
 
PS> ./test.ps1 @params

Atributos de Parâmetro PowerShell

As características do parâmetro permitem que você mude a funcionalidade do parâmetro de várias maneiras. Você pode usar expressões regulares para se adequar a uma expressão regular, exigir o uso de um dado parâmetro e verificar os valores fornecidos a um parâmetro.

Parâmetros Obrigatórios

No PowerShell, podemos exigir um ou mais atributos funcionando em uma função com base em nossa vontade. Portanto, podemos usar o atributo mandatory dentro da construção Parameter().

param(
    [Parameter(Mandatory)]
    [string]$Param1,
 
    [Parameter()]
    [string]$Param2,
 
    [Parameter()]
    [switch]$DisplayParam2
)
 
Write-Host "Param1 value is $Param1"
if ($DisplayParam2.IsPresent) {
    Write-Host "Param2 value is $Param2"
}

Saída:

Validação de Parâmetro

Finalmente, verifique se os valores fornecidos aos parâmetros estão corretos. É ideal para manter a possibilidade de alguém fornecer um valor único a um parâmetro ao mínimo. Portanto, podemos especificar os inputs que queremos usando o ‘ValidateSet()’, conforme mostrado abaixo.

param(
    [Parameter(Mandatory)]
    [ValidateSet('x', 'y')]
    [string]$Param1,
 
    [Parameter()]
    [string]$Param2,
 
    [Parameter()]
    [switch]$DisplayParam2
)
 
Write-Host "Param1 value is $Param1"
if ($DisplayParam2.IsPresent) {
    Write-Host "Param2 value is $Param2"
}

Se fornecermos valores diferentes de x e y para param1, um erro aparecerá.

Função Avançada Com Sintaxe de Parâmetro Nomeado

Quando o atributo Cmdletbinding é adicionado a uma função, isso a transforma em uma função avançada. Outros argumentos comuns são usados quando a função avançada é construída. A sintaxe é a seguinte.

function testfunction {
    [CmdletBinding (DefaultParameterSetName = 'Param1')]
    Param
    (
        [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'Param1')]
        [string] Param1,
        [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'Param2')]
        [string] Param2,
    )
}