Como usar o atributo CmdletBinding no PowerShell

O cmdlet é um script leve que executa uma única função dentro do ambiente PowerShell. Os cmdlets podem ser escritos em qualquer linguagem .Net.

Geralmente, um cmdlet é expresso como um par verbo-substantivo para executar um comando. O comando é uma ordem para o sistema operacional subjacente realizar um serviço específico pelo usuário final.

O ambiente PowerShell inclui mais de 200 cmdlets básicos, como New-Item, Move-Item, Set-Location e Get-Location. O cmdlet compartilha um conjunto comum de recursos não disponíveis em funções simples do PowerShell.

1. Suporta parâmetros comuns, como -WhatIf, ErrorAction, Verbose, etc.
2. Solicita confirmações
3. Suporte a parâmetros obrigatórios

Atributo CmdletBinding no PowerShell

A simples função PowerShell pode ser escrita como uma função avançada herdando os recursos básicos de cmdlet discutidos acima. O atributo CmdletBinding permite que você acesse esses recursos básicos de cmdlet.

A seguir, mostra a sintaxe do atributo CmdletBinding com todos os argumentos possíveis.

{
    [CmdletBinding(ConfirmImpact = <String>,
        DefaultParameterSetName = <String>,
        HelpURI = <URI>,
        SupportsPaging = <Boolean>,
        SupportsShouldProcess = <Boolean>,
        PositionalBinding = <Boolean>)]

    Param ($myparam)
    Begin {}
    Process {}
    End {}
}

Vamos supor que temos uma função simples do PowerShell chamada Helloworld-To-UpperCase.

Function Helloworld-To-UpperCase {
    "helloworld".ToUpper();
}

Não há parâmetros anexados a essa função. Portanto, isso é chamado de uma função simples do PowerShell.

Mas podemos usar o atributo CmdletBinding para converter essa função em uma avançada e acessar os recursos e parâmetros básicos de cmdlet, como mostrado a seguir.

Function Helloworld-To-UpperCase {
    [CmdletBinding()]Param()
    "helloworld".ToUpper();
}

A função Helloworld-To-UpperCase foi convertida em uma função avançada que herda todos os recursos básicos do cmdlet. Os parâmetros básicos do cmdlet estão disponíveis para esta função.

Se você chamar esta função com - na janela do PowerShell, ele deverá listar todos os parâmetros comuns provenientes do cmdlet.

helloworld-to-uppercase -

Saída:

Os parâmetros e recursos comuns do cmdlet podem ser usados dentro de nossas funções avançadas para estender a funcionalidade.

Use o Atributo CmdletBinding Com o Parâmetro Verbose

O -verbose é um dos valiosos parâmetros comuns que pode exibir uma mensagem quando a função avançada é executada.

Function Helloworld-To-UpperCase {
    [CmdletBinding()]Param()

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    "helloworld".ToUpper();
}

Quando chamamos a função acima com o parâmetro -verbose, ele imprimirá todas as strings Write-Verbose na janela do PowerShell.

HelloWorld-To-UpperCase -Verbose

Saída:

Use o Atributo CmdletBinding Com o Objeto $PSCmdlet e SupportsShouldProcess

Como usamos o atributo CmdletBinding, nossa função avançada pode acessar o objeto $PSCmdlet sem problemas. Este objeto contém vários métodos, como ShouldContinue, ShouldProcess, ToString, WriteDebug, etc.

Use o Atributo CmdletBinding Com o Método ShouldContinue

Este método permite que os usuários lidem com solicitações de confirmação. Nesse meio tempo, é obrigatório definir o argumento SupportsShouldProcess como $True.

O método ShouldContinue possui vários métodos sobrecarregados, e usaremos o que tem dois parâmetros.

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess = $True)]Param()

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        "helloworld".ToUpper();
    }
    Else {
        "helloworld kept in lowercase."
    }
}

Podemos chamar a função com o parâmetro -Confirm, e ele exibirá uma caixa de confirmação, como mostrado a seguir.

HelloWorld-To-UpperCase -Confirm

Saída:

Se o usuário clicar em Sim, deve implementar o método no bloco if e imprimir a string helloworld em letras maiúsculas.

Caso contrário, deverá mostrar a mensagem helloworld mantido em minúsculas.

Use o Atributo CmdletBinding Com o Atributo Parameter Para Controlar Parâmetros da Função

Vamos fazer nossa função avançada aceitar um parâmetro como uma string.

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess = $True)]
    Param([string]$word)

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        $word.ToUpper();
    }
    Else {
        "helloworld kept in lowercase."
    }
}

Mudamos a função Helloworld-To-UpperCase para aceitar um parâmetro do tipo string chamado $word. Quando a função é chamada, precisamos fornecer uma string como argumento.

O texto fornecido será convertido para letras maiúsculas. Se o usuário não forneceu nenhum argumento de texto, a função retornará uma saída vazia.

Podemos controlar isso tornando o parâmetro $word obrigatório e dando à posição do parâmetro 0.

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess = $True)]
    Param(
        [Parameter(
            Mandatory = $True, Position = 0
        ) ]
        [string]$word
    )

    #Verbose
    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    #If/Else block for request processing
    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        $word.ToUpper();
    }
    Else {
        "helloworld kept in lowercase."
    }
}

Adicionamos algumas flags para controlar o comportamento do parâmetro $word. Como é obrigatório, precisamos fornecer um valor de string quando a função for executada.

HelloWorld-To-UpperCase -Confirm "stringtouppercase"

O PowerShell continua perguntando por isso se não fornecermos o argumento de texto.

Você pode usar várias flags para controlar os parâmetros em suas funções, como mostrado na seguinte sintaxe do atributo Parameter.

Param
(
    [Parameter(
        Mandatory = <Boolean>,
        Position = <Integer>,
        ParameterSetName = <String>,
        ValueFromPipeline = <Boolean>,
        ValueFromPipelineByPropertyName = <Boolean>,
        ValueFromRemainingArguments = <Boolean>,
        HelpMessage = <String>,
    )]
    [string[]]
    $Parameter1
)