Comment utiliser l'attribut CmdletBinding dans PowerShell

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

Le cmdlet est un script léger qui effectue une seule fonction dans l’environnement PowerShell. Les cmdlets peuvent être écrits dans n’importe quel langage .Net.

En général, un cmdlet se présente sous la forme d’une paire verbe-nom pour exécuter une commande. La commande est une ordre au système d’exploitation sous-jacent d’effectuer un service spécifique par l’utilisateur final.

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

1. Prend en charge des paramètres communs tels que -WhatIf, ErrorAction, Verbose, etc.
2. Invite à 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 caractéristiques de base du cmdlet discutées ci-dessus. L’attribut CmdletBinding vous permet d’accéder à ces fonctionnalités de base du cmdlet.

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

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

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

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

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

Il n’y a pas de paramètres attachés à cette fonction. Donc, c’est ce qu’on appelle une fonction PowerShell simple.

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 du cmdlet, comme le montre ce qui suit.

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

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

 powershellCopyHelloWorld-To-UpperCase -Verbose

Sortie :

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

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

Utilisez 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 allons utiliser celle avec deux paramètres.

 powershellCopyFunction 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 montré ci-dessous.

 powershellCopyHelloWorld-To-UpperCase -Confirm

Sortie :

Si l’utilisateur clique sur Oui, cela devrait mettre en œuvre la méthode dans le bloc if et imprimer la chaîne helloworld en majuscules.

Sinon, cela devrait afficher le message helloworld gardé en minuscules.

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

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

 powershellCopyFunction 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 qu’elle prenne un paramètre de type chaîne appelé $word. Lorsque la fonction est appelée, nous devons fournir une chaîne comme argument.

Le texte fourni sera converti en majuscules. Si l’utilisateur n’a pas fourni d’argument texte, la fonction donnera une sortie vide.

Nous pouvons contrôler cela en rendant le paramètre $word obligatoire et en lui donnant la position de paramètre 0.

 powershellCopyFunction 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 indicateurs pour contrôler le comportement du paramètre $word. Puisqu’il est obligatoire, nous devons fournir une valeur de chaîne lorsque la fonction est exécutée.

 powershellCopyHelloWorld-To-UpperCase -Confirm "stringtouppercase"

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

Vous pouvez utiliser plusieurs indicateurs pour contrôler les paramètres dans vos fonctions, comme l’indique la syntaxe suivante de l’attribut Parameter.

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