about_Functions_CmdletBindingAttribute
Description courte
Décrit l’attribut qui fait qu’une fonction fonctionne comme une applet de commande compilée.
Description longue
L’attribut CmdletBinding est un attribut de fonctions qui les fait fonctionner comme des applets de commande compilées écrites en C#. Il permet d’accéder aux fonctionnalités des applets de commande.
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 pas de paramètres positionnels correspondants entraînent l’échec de la liaison de paramètres.
Notes
Les applets de commande compilées utilisent l’attribut requis Cmdlet , qui est similaire à l’attribut CmdletBinding décrit dans cette rubrique.
Syntax
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 en cas d’omission de l’attribut CmdletBinding . Définissez la valeur de l’argument sur $true ou répertoriez 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 Moyenne.) 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 jeu de paramètres à utiliser. Vous pouvez éviter ce problème en faisant du paramètre unique de chaque paramètre défini 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 les fichiers d’aide sont installés sur l’ordinateur et que la valeur du premier lien dans la section RelatedLinks du fichier d’aide est un URI, ou que la valeur de la première .Link directive de l’aide basée sur les 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 la fonction lorsque le paramètre Online de Get-Help est 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 grands magasins de données 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.
- First : obtient uniquement les premiers objets « n ».
- Skip : ignore les premiers objets « n », puis obtient les objets restants.
- IncludeTotalCount : indique 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 du nombre total à retourner et inclut une estimation de la précision de la valeur du 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 les 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 la valeur pour désactiver la $False 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 sans nom aux paramètres de fonction en fonction de l’ordre ou de la position des valeurs de paramètre sans nom 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 a la valeur $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 a la valeur $False, les paramètres de fonction ne sont pas positionnels par défaut. Sauf si l’argument Position de l’attribut Parameter 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