Come utilizzare l'attributo CmdletBinding in PowerShell

Il cmdlet è uno script leggero che svolge una singola funzione all’interno dell’ambiente PowerShell. I cmdlet possono essere scritti in qualsiasi linguaggio .Net.

Di solito, un cmdlet è espresso come una coppia verbo-nome per eseguire un comando. Il comando è un ordine al sistema operativo sottostante di eseguire un servizio specifico da parte dell’utente finale.

L’ambiente PowerShell include più di 200 cmdlet di base come New-Item, Move-Item, Set-Location e Get-Location. I cmdlet condividono un insieme comune di caratteristiche non disponibili nelle semplici funzioni PowerShell.

1. Supporta parametri comuni come -WhatIf, ErrorAction, Verbose, ecc.
2. Richiesta di conferma
3. Supporto dei parametri obbligatori

Attributo CmdletBinding in PowerShell

La semplice funzione PowerShell può essere scritta come una funzione avanzata ereditando le caratteristiche di base del cmdlet discusse sopra. L’attributo CmdletBinding ti consente di accedere a queste caratteristiche di base del cmdlet.

Di seguito viene mostrata la sintassi dell’attributo CmdletBinding con tutti i possibili argomenti.

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

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

Diciamo di avere una semplice funzione PowerShell chiamata Helloworld-To-UpperCase.

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

Non ci sono parametri attaccati a questa funzione. Quindi, questa è chiamata una semplice funzione PowerShell.

Ma possiamo usare l’attributo CmdletBinding per convertire questa funzione in una avanzata e accedere alle caratteristiche e ai parametri di base del cmdlet, come mostrato di seguito.

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

La funzione Helloworld-To-UpperCase è stata convertita in una funzione avanzata che eredita tutte le caratteristiche di base del cmdlet. I parametri di base del cmdlet sono disponibili per questa funzione.

Se chiami questa funzione con - nella finestra di PowerShell, dovrebbe elencare tutti i parametri comuni provenienti dal cmdlet.

helloworld-to-uppercase -

Output:

I parametri e le caratteristiche comuni del cmdlet possono essere utilizzati all’interno delle nostre funzioni avanzate per estendere la funzionalità.

Utilizza l’attributo CmdletBinding con il parametro Verbose

Il -verbose è uno dei parametri comuni preziosi che può visualizzare un messaggio quando la funzione avanzata viene eseguita.

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

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

    "helloworld".ToUpper();
}

Quando chiamiamo la funzione sopra con il parametro -verbose, stamperà tutte le stringhe Write-Verbose nella finestra di PowerShell.

HelloWorld-To-UpperCase -Verbose

Output:

Utilizza l’attributo CmdletBinding con l’oggetto $PSCmdlet e SupportsShouldProcess

Poiché abbiamo utilizzato l’attributo CmdletBinding, la nostra funzione avanzata può accedere all’oggetto $PSCmdlet senza problemi. Questo oggetto contiene diversi metodi come ShouldContinue, ShouldProcess, ToString, WriteDebug, ecc.

Utilizza l’attributo CmdletBinding con il metodo ShouldContinue

Questo metodo consente agli utenti di gestire le richieste di conferma. Nel frattempo, è obbligatorio impostare l’argomento SupportsShouldProcess su $True.

Il metodo ShouldContinue ha diversi metodi sovraccaricati, e utilizzeremo quello con due parametri.

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."
    }
}

Possiamo chiamare la funzione con il parametro -Confirm, e mostrerà una casella di conferma come mostrato di seguito.

HelloWorld-To-UpperCase -Confirm

Output:

Se l’utente fa clic su Sì, dovrebbe implementare il metodo nel blocco if e stampare la stringa helloworld in lettere maiuscole.

In caso contrario, dovrebbe mostrare il messaggio helloworld mantenuto in minuscolo.

Utilizza l’attributo CmdletBinding con l’attributo Parameter per controllare i parametri della funzione

Facciamo in modo che la nostra funzione avanzata prenda un parametro come stringa.

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."
    }
}

Abbiamo cambiato la funzione Helloworld-To-UpperCase per prendere un parametro di tipo stringa chiamato $word. Quando la funzione viene chiamata, dobbiamo fornire una stringa come argomento.

Il testo fornito verrà convertito in maiuscolo. Se l’utente non ha fornito alcun argomento testuale, la funzione restituirà un output vuoto.

Possiamo controllare questo rendendo il parametro $word obbligatorio e dando la posizione del parametro 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."
    }
}

Abbiamo aggiunto alcuni flag per controllare il comportamento del parametro $word. Poiché è obbligatorio, dobbiamo fornire un valore stringa quando la funzione viene eseguita.

HelloWorld-To-UpperCase -Confirm "stringtouppercase"

PowerShell continua a chiedere questo se non forniamo l’argomento di testo.

Puoi utilizzare diversi flag per controllare i parametri nelle tue funzioni, come mostrato nella seguente sintassi dell’attributo Parameter.

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