about_Functions_CmdletBindingAttribute

  • Article

Description courte

Décrit l’attribut qui rend une fonction fonctionne comme une applet de commande compilée.

Description longue

L’attribut CmdletBinding est un attribut de fonctions qui les rend fonctionnent comme des applets de commande compilées écrites en C#. Il fournit l’accès aux fonctionnalités des applets de commande.

Lorsque vous utilisez l’attribut CmdletBinding , PowerShell ajoute automatiquement les paramètres communs. Vous ne pouvez pas créer de paramètres qui utilisent les mêmes noms que les paramètres communs. Pour plus d’informations, consultez about_CommonParameters.

PowerShell lie les paramètres des fonctions qui ont l’attribut CmdletBinding de la même façon qu’il lie les paramètres des applets de commande compilées. La $PSCmdlet variable automatique est disponible pour les fonctions avec l’attribut CmdletBinding , mais la $Args variable n’est pas disponible.

Dans les fonctions qui ont l’attribut CmdletBinding , les paramètres inconnus et les arguments positionnels qui n’ont aucun paramètre positionnel correspondant provoquent l’échec de la liaison de paramètres.

Remarque

Les applets de commande compilées utilisent l’attribut requis Cmdlet , qui est similaire à l’attribut CmdletBinding décrit dans cette rubrique.

Syntaxe

L’exemple suivant montre le format d’une fonction qui spécifie tous les arguments facultatifs de l’attribut CmdletBinding . Une brève description de chaque argument suit cet exemple.

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

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

Les types d’arguments booléens de l’attribut CmdletBinding ont la valeur False par défaut lorsqu’ils sont omis à partir de l’attribut CmdletBinding. Définissez la valeur de $true l’argument sur ou listez simplement l’argument par nom. Par exemple, les attributs CmdletBinding suivants sont équivalents.

{
    [CmdletBinding(SupportsPaging=$true)]

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

# Boolean arguments can be defined using this shorthand syntax

{
    [CmdletBinding(SupportsPaging)]

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

ConfirmImpact

L’argument ConfirmImpact spécifie quand l’action de la fonction doit être confirmée par un appel à la méthode ShouldProcess . L’appel à la méthode ShouldProcess affiche une invite de confirmation uniquement lorsque l’argument ConfirmImpact est égal ou supérieur à la valeur de la $ConfirmPreference variable de préférence. (La valeur par défaut de l’argument est Moyen.) Spécifiez cet argument uniquement lorsque l’argument SupportsShouldProcess est également spécifié.

Pour plus d’informations sur les demandes de confirmation, consultez Demande de confirmation.

DefaultParameterSetName

L’argument DefaultParameterSetName spécifie le nom du jeu de paramètres que PowerShell tente d’utiliser lorsqu’il ne peut pas déterminer le paramètre à utiliser. Vous pouvez éviter ce problème en rendant le paramètre unique de chaque jeu de paramètres un paramètre obligatoire.

HelpURI

L’argument HelpURI spécifie l’adresse Internet de la version en ligne de la rubrique d’aide qui décrit la fonction. La valeur de l’argument HelpURI doit commencer par « http » ou « https ».

La valeur de l’argument HelpURI est utilisée pour la valeur de la propriété HelpURI de l’objet CommandInfo qui Get-Command retourne pour la fonction.

Toutefois, lorsque des fichiers d’aide sont installés sur l’ordinateur et que la valeur du premier lien de la section RelatedLinks du fichier d’aide est un URI, ou que la valeur de la première .Link directive dans l’aide basée sur des commentaires est un URI, l’URI du fichier d’aide est utilisé comme valeur de la propriété HelpUri de la fonction.

L’applet Get-Help de commande utilise la valeur de la propriété HelpURI pour localiser la version en ligne de la rubrique d’aide de fonction lorsque le paramètre Online d’est Get-Help spécifié dans une commande.

SupportsPaging

L’argument SupportsPaging ajoute les paramètres First, Skip et IncludeTotalCount à la fonction. Ces paramètres permettent aux utilisateurs de sélectionner la sortie d’un jeu de résultats très volumineux. Cet argument est conçu pour les applets de commande et les fonctions qui retournent des données à partir de magasins de données volumineux qui prennent en charge la sélection des données, comme une base de données SQL.

Cet argument a été introduit dans Windows PowerShell 3.0.

  • Tout d’abord : obtient uniquement les premiers objets 'n'.
  • Ignorer : ignore les premiers objets « n », puis obtient les objets restants.
  • IncludeTotalCount : signale le nombre d’objets dans le jeu de données (un entier) suivi des objets. Si l’applet de commande ne peut pas déterminer le nombre total, elle retourne « Nombre total inconnu ».

PowerShell inclut NewTotalCount, une méthode d’assistance qui obtient la valeur de nombre total à retourner et inclut une estimation de la précision de la valeur de nombre total.

L’exemple de fonction suivant montre comment ajouter la prise en charge des paramètres de pagination à une fonction avancée.

function Get-Numbers {
    [CmdletBinding(SupportsPaging)]
    param()

    $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
    $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First +
      $FirstNumber - 1, 100)

    if ($PSCmdlet.PagingParameters.IncludeTotalCount) {
        $TotalCountAccuracy = 1.0
        $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100,
          $TotalCountAccuracy)
        Write-Output $TotalCount
    }
    $FirstNumber .. $LastNumber | Write-Output
}

SupportsShouldProcess

L’argument SupportsShouldProcess ajoute des paramètres Confirm et WhatIf à la fonction. Le paramètre Confirm invite l’utilisateur avant d’exécuter la commande sur chaque objet du pipeline. Le paramètre WhatIf répertorie les modifications apportées par la commande au lieu d’exécuter la commande.

PositionalBinding

L’argument PositionalBinding détermine si les paramètres de la fonction sont positionnels par défaut. La valeur par défaut est $True. Vous pouvez utiliser l’argument PositionalBinding avec une valeur de désactivation de $False la liaison positionnelle.

L’argument PositionalBinding est introduit dans Windows PowerShell 3.0.

Lorsque les paramètres sont positionnels, le nom du paramètre est facultatif. PowerShell associe des valeurs de paramètre non nommées aux paramètres de fonction en fonction de l’ordre ou de la position des valeurs de paramètre non nommées dans la commande de fonction.

Lorsque les paramètres ne sont pas positionnels (ils sont « nommés »), le nom du paramètre (ou une abréviation ou un alias du nom) est requis dans la commande.

Lorsque PositionalBinding est $True, les paramètres de fonction sont positionnels par défaut. PowerShell affecte le numéro de position aux paramètres dans l’ordre dans lequel ils sont déclarés dans la fonction.

Lorsque PositionalBinding est $False, les paramètres de fonction ne sont pas positionnels par défaut. Sauf si l’argument Position de l’attribut Paramètre est déclaré sur le paramètre, le nom du paramètre (ou un alias ou une abréviation) doit être inclus lorsque le paramètre est utilisé dans une fonction.

L’argument Position de l’attribut Parameter est prioritaire sur la valeur par défaut PositionalBinding. Vous pouvez utiliser l’argument Position pour spécifier une valeur de position pour un paramètre. Pour plus d’informations sur l’argument Position , consultez about_Functions_Advanced_Parameters.

Notes

L’argument SupportsTransactions n’est pas pris en charge dans les fonctions avancées .

Mots clés

about_Functions_CmdletBinding_Attribute

Voir aussi