Como usar o atributo CmdletBinding no PowerShell

1. Atributo CmdletBinding no PowerShell
2. Use o Atributo CmdletBinding Com o Parâmetro Verbose
3. Use o Atributo CmdletBinding Com o Objeto $PSCmdlet e SupportsShouldProcess
4. Use o Atributo CmdletBinding Com o Atributo Parameter Para Controlar Parâmetros da Função

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();
}

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
)