Utiliser l'attribut CmdletBinding dans PowerShell

1. Attribut CmdletBinding dans PowerShell
2. Utiliser l’attribut CmdletBinding avec le paramètre Verbose
3. Utiliser l’attribut CmdletBinding avec l’objet $PSCmdlet et SupportsShouldProcess
4. Utiliser l’attribut CmdletBinding avec l’attribut Parameter pour contrôler les paramètres de la fonction

La cmdlet est un script léger qui exécute une seule fonction dans l’environnement PowerShell. Les cmdlets peuvent être écrites dans n’importe quel langage .Net.

Habituellement, une cmdlet est exprimée sous la forme d’une paire verbe-nom pour exécuter une commande. La commande est une commande au système d’exploitation sous-jacent d’exécuter un service spécifique par l’utilisateur final.

L’environnement PowerShell comprend plus de 200 cmdlets de base telles que New-Item, Move-Item, Set-Location et Get-Location. Les cmdlets partagent un ensemble commun de fonctionnalités non disponibles dans les fonctions PowerShell simples.

1. Prend en charge les paramètres communs tels que -WhatIf, ErrorAction, Verbose, etc.
2. Demander des confirmations
3. Prise en charge des paramètres obligatoires

Attribut CmdletBinding dans PowerShell

La fonction PowerShell simple peut être écrite comme une fonction avancée en héritant des fonctionnalités de base de la cmdlet décrites ci-dessus. L’attribut CmdletBinding vous permet d’accéder à ces fonctionnalités de base cmdlet.

Ce qui suit montre la syntaxe de l’attribut CmdletBinding avec tous les arguments possibles.

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

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

Disons que nous avons une simple fonction PowerShell appelée Helloworld-To-UpperCase.

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

Aucun paramètre n’est associé à cette fonction. Donc, cela s’appelle une simple fonction PowerShell.

Mais nous pouvons utiliser l’attribut CmdletBinding pour convertir cette fonction en une fonction avancée et accéder aux fonctionnalités et paramètres de base de cmdlet, comme indiqué ci-dessous.

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

La fonction Helloworld-To-UpperCase a été convertie en une fonction avancée qui hérite de toutes les fonctionnalités de base de la cmdlet. Les paramètres cmdlet de base sont disponibles pour cette fonction.

Si vous appelez cette fonction avec - dans la fenêtre PowerShell, elle devrait lister tous les paramètres communs provenant de la cmdlet.

helloworld-to-uppercase -

Production:

Les paramètres et fonctionnalités communs de cmdlet peuvent être utilisés dans nos fonctions avancées pour étendre la fonctionnalité.

Utiliser l’attribut CmdletBinding avec le paramètre Verbose

Le -verbose est l’un des paramètres communs précieux qui peuvent afficher un message lorsque la fonction avancée est exécutée.

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

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

    "helloworld".ToUpper();
}

Lorsque nous appelons la fonction ci-dessus avec le paramètre -verbose, elle imprimera toutes les chaînes Write-Verbose dans la fenêtre PowerShell.

HelloWorld-To-UpperCase -Verbose

Production:

Utiliser l’attribut CmdletBinding avec l’objet $PSCmdlet et SupportsShouldProcess

Depuis que nous avons utilisé l’attribut CmdletBinding, notre fonction avancée peut accéder à l’objet $PSCmdlet sans tracas. Cet objet contient plusieurs méthodes telles que ShouldContinue, ShouldProcess, ToString, WriteDebug, etc.

Utiliser l’attribut CmdletBinding avec la méthode ShouldContinue

Cette méthode permet aux utilisateurs de gérer les demandes de confirmation. En attendant, il est obligatoire de définir l’argument SupportsShouldProcess sur $True.

La méthode ShouldContinue a plusieurs méthodes surchargées, et nous utiliserons celle avec deux paramètres.

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

Nous pouvons appeler la fonction avec le paramètre -Confirm, et elle affichera une boîte de confirmation comme indiqué ci-dessous.

HelloWorld-To-UpperCase -Confirm

Production:

Si l’utilisateur clique sur Yes, il doit implémenter la méthode dans le bloc if et imprimer la chaîne helloworld en lettres majuscules.

Si ce n’est pas le cas, il devrait afficher le message helloworld kept in lowercase.

Utiliser l’attribut CmdletBinding avec l’attribut Parameter pour contrôler les paramètres de la fonction

Faisons en sorte que notre fonction avancée prenne un paramètre sous forme de chaîne.

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

Nous avons changé la fonction Helloworld-To-UpperCase pour prendre un paramètre de type chaîne appelé $word. Lorsque la fonction a été appelée, nous devons fournir une chaîne en argument.

Le texte fourni sera converti en majuscule. Si l’utilisateur n’a fourni aucun argument de texte, la fonction donnera une sortie vide.

On peut contrôler cela en rendant obligatoire le paramètre $word et en donnant la position de paramètre 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."
    }
}

Nous avons ajouté quelques drapeaux pour contrôler le comportement du paramètre $word. Comme c’est obligatoire, nous devons fournir une valeur de chaîne lorsque la fonction s’exécute.

HelloWorld-To-UpperCase -Confirm "stringtouppercase"

PowerShell continue de demander cela si nous ne fournissons pas l’argument de texte.

Vous pouvez utiliser plusieurs drapeaux pour contrôler les paramètres dans vos fonctions, comme indiqué dans la syntaxe d’attribut Parameter suivante.

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