about_Functions_Advanced_Parameters

Mis à jour: mai 2014

S'applique à: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

RUBRIQUE

Insérez le corps de la section ici.

DESCRIPTION COURTE

Explique comment ajouter des paramètres à des fonctions avancées.

DESCRIPTION DÉTAILLÉE

Vous pouvez ajouter des paramètres aux fonctions avancées que vous écrivez et utiliser les attributs et arguments de paramètre pour limiter les valeurs de paramètre envoyées par les utilisateurs des fonctions avec le paramètre.

Les paramètres que vous ajoutez à votre fonction sont disponibles pour les utilisateurs en plus des paramètres courants que Windows PowerShell® ajoute automatiquement à toutes les applets de commande et fonctions avancées. Pour plus d'informations sur les paramètres courants Windows PowerShell, consultez about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

À compter de Windows PowerShell 3.0, vous pouvez utiliser la projection avec @Args pour représenter les paramètres dans une commande. Cette technique est valide sur des fonctions simples et avancées. Pour plus d'informations, consultez about_Functions (https://go.microsoft.com/fwlink/?LinkID=113231) et about_Splatting (https://go.microsoft.com/fwlink/?LinkID=262720).

PARAMÈTRES STATIQUES

Les paramètres statiques sont des paramètres qui sont toujours disponibles dans la fonction. La plupart des paramètres dans les applets de commande et les scripts Windows PowerShell sont des paramètres statiques.

L'exemple suivant illustre la déclaration d'un paramètre ComputerName qui présente les caractéristiques suivantes :

Il est obligatoire (requis).

Il accepte l'entrée provenant du pipeline.

Il accepte un tableau de chaînes comme entrée.

        Param
          (
            [parameter(Mandatory=$true,
            ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          )

ATTRIBUTS DE PARAMÈTRES

Cette section décrit les attributs que vous pouvez ajouter aux paramètres de fonction.

Tous les attributs sont facultatifs. Toutefois, si vous omettez l'attribut CmdletBinding, la fonction doit inclure l'attribut Parameter pour être reconnue comme fonction avancée.

Vous pouvez ajouter un ou plusieurs attributs à chaque déclaration de paramètre. Il n'existe aucune limite au nombre d'attributs que vous pouvez ajouter à une déclaration de paramètre.

ATTRIBUT PARAMETER

L'attribut Parameter est utilisé pour déclarer les attributs des paramètres de fonction.

L'attribut Parameter est facultatif et vous pouvez l'omettre si aucun des paramètres de vos fonctions ne nécessite d'attributs, mais une fonction doit avoir l'attribut CmdletBinding ou Parameter, ou les deux, pour être reconnue comme fonction avancée (et non comme fonction simple).

L'attribut Parameter a des arguments qui définissent les caractéristiques du paramètre, par exemple si le paramètre est obligatoire ou facultatif.

Utilisez la syntaxe suivante pour déclarer l'attribut Parameter, un argument et une valeur d'argument. Les parenthèses qui entourent l'argument et sa valeur doivent suivre « Parameter » sans espace intermédiaire.

        Param
          (
            [parameter(Argument=value)]
            $ParameterName
          )

Utilisez des virgules pour séparer les arguments entre parenthèses. Utilisez la syntaxe suivante pour déclarer deux arguments de l'attribut Parameter.

        Param
          (
            [parameter(Argument1=value1,
                       Argument2=value2)]

          )

Si vous utilisez l'attribut Parameter sans arguments (comme alternative à l'utilisation de l'attribut CmdletBinding), les parenthèses qui suivent le nom d'attribut sont toujours nécessaires.

        Param
          (
            [parameter()]
            $ParameterName
          )

Argument Mandatory

L'argument Mandatory indique que le paramètre est requis. Si cet argument n'est pas spécifié, le paramètre est un paramètre facultatif.

L'exemple suivant déclare le paramètre ComputerName. Il utilise l'argument Mandatory pour rendre le paramètre obligatoire.

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            $ComputerName
          )

Argument Position

L'argument Position détermine si le nom du paramètre est requis quand le paramètre est utilisé dans une commande. Quand une déclaration de paramètre inclut l'argument Position, le nom du paramètre peut être omis et Windows PowerShell identifie la valeur du paramètre sans nom par sa position (ou ordre) dans la liste des valeurs de paramètre sans nom de la commande.

Si l'argument Position n'est pas spécifié, le nom du paramètre (ou un alias de nom de paramètre ou une abréviation) doit précéder la valeur de paramètre chaque fois que le paramètre est utilisé dans une commande.

Par défaut, tous les paramètres de fonction sont positionnels. Windows PowerShell affecte des numéros de positions aux paramètres dans l'ordre dans lequel ils sont déclarés dans la fonction. Pour désactiver cette fonctionnalité, affectez la valeur $False à l'argument PositionalBinding de l'attribut CmdletBinding. L'argument Position est prioritaire sur la valeur de l'argument PositionalBinding pour les paramètres sur lesquels il est déclaré. Pour plus d'informations, consultez PositionalBinding dans about_Functions_CmdletBindingAttribute.

La valeur de l'argument Position est spécifiée en tant qu'entier. La valeur de position 0 représente la première position dans la commande, la valeur de position 1 représente la deuxième position dans la commande, et ainsi de suite.

Si une fonction ne comporte pas de paramètres positionnels, Windows PowerShell affecte des positions à chaque paramètre selon l'ordre dans lequel les paramètres sont déclarés. Toutefois, il est recommandé de ne pas compter sur cette affectation. Quand vous souhaitez que les paramètres soient positionnels, utilisez l'argument Position.

L'exemple suivant déclare le paramètre ComputerName. Il utilise l'argument Position avec la valeur 0. Par conséquent, quand « -ComputerName » est omis de la commande, sa valeur doit être la première ou la seule valeur de paramètre sans nom dans la commande.

        Param
          (
            [parameter(Position=0)]
            [String[]]
            $ComputerName
          )

REMARQUE :

Quand l'applet de commande Get-Help affiche l'attribut de paramètre « Position? » correspondant, la valeur de position est incrémentée de 1. Par exemple, un paramètre avec une valeur d'argument Position 0 a un attribut de paramètre « Position? 1."

Argument ParameterSetName

L'argument ParameterSetName spécifie le jeu de paramètres auquel appartient un paramètre. Si aucun jeu de paramètres n'est spécifié, le paramètre appartient à tous les jeux de paramètres définis par la fonction. Par conséquent, pour être unique, chaque jeu de paramètres doit comporter au moins un paramètre qui n'est pas membre d'un autre jeu de paramètres.

L'exemple suivant déclare un paramètre ComputerName dans le jeu de paramètres Computer, un paramètre UserName dans le jeu de paramètres User et un paramètre Summary dans les deux jeux de paramètres.

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")]
            [String[]]
            $ComputerName,

            [parameter(Mandatory=$true,
                      ParameterSetName="User")]
            [String[]]
            $UserName,

            [parameter(Mandatory=$false)]
            [Switch]
            $Summary
          )

Vous ne pouvez spécifier qu'une seule valeur ParameterSetName dans chaque argument et qu'un seul argument ParameterSetName dans chaque attribut Parameter. Pour indiquer qu'un paramètre figure dans plusieurs jeux de paramètres, ajoutez d'autres attributs Parameter.

L'exemple suivant ajoute explicitement le paramètre Summary aux jeux de paramètres Computer et User. Le paramètre Summary est obligatoire dans un jeu de paramètres et facultatif dans l'autre.

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")]
            [String[]]
            $ComputerName,

            [parameter(Mandatory=$true,
                      ParameterSetName="User")]
            [String[]]
            $UserName,

            [parameter(Mandatory=$false, ParameterSetName="Computer")]
            [parameter(Mandatory=$true, ParameterSetName="User")]
            [Switch]
            $Summary
          )
        

Pour plus d'informations sur les jeux de paramètres, consultez « Jeux de paramètres d'applet de commande » dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkId=142183.

Argument ValueFromPipeline

L'argument ValueFromPipeline indique que le paramètre accepte l'entrée d'un objet de pipeline. Spécifiez cet argument si la fonction accepte l'intégralité de l'objet, et non uniquement une propriété de l'objet.

L'exemple suivant déclare un paramètre ComputerName qui est obligatoire et accepte un objet qui est passé à la fonction à partir du pipeline.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          )

Argument ValueFromPipelineByPropertyName

L'argument valueFromPipelineByPropertyName indique que le paramètre accepte l'entrée d'une propriété d'un objet de pipeline. La propriété de l'objet doit avoir le même nom ou alias que le paramètre.

Par exemple, si la fonction a un paramètre ComputerName et l'objet redirigé a une propriété ComputerName, la valeur de la propriété ComputerName est affectée au paramètre ComputerName de la fonction.

L'exemple suivant déclare un paramètre ComputerName qui est obligatoire et accepte l'entrée de la propriété ComputerName de l'objet qui est passé à la fonction via le pipeline.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipelineByPropertyName=$true)]
            [String[]]
            $ComputerName
          )

Argument ValueFromRemainingArguments

L'argument ValueFromRemainingArguments indique que le paramètre accepte toutes les valeurs des paramètres dans la commande qui ne sont pas affectées à d'autres paramètres de la fonction.

L'exemple suivant déclare un paramètre ComputerName qui est obligatoire et accepte toutes les valeurs de paramètre restantes qui ont été envoyées à la fonction.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromRemainingArguments=$true)]
            [String[]]
            $ComputerName
          )

Argument HelpMessage

L'argument HelpMessage spécifie une chaîne qui contient une brève description du paramètre ou sa valeur. Windows PowerShell affiche ce message dans l'invite qui s'affiche quand une valeur de paramètre obligatoire est manquante dans une commande. Cet argument n'a aucun effet sur les paramètres facultatifs.

L'exemple suivant déclare un paramètre ComputerName obligatoire et un message d'aide qui explique la valeur de paramètre attendue.

        Param
          (
            [parameter(mandatory=$true,
                       HelpMessage="Enter one or more computer names separated by commas.")]
            [String[]]
            $ComputerName
          )

ATTRIBUT ALIAS

L'attribut Alias établit un autre nom pour le paramètre. Il n'existe aucune limite au nombre d'alias que vous pouvez affecter à un paramètre.

L'exemple suivant illustre une déclaration de paramètre qui ajoute les alias « CN » et « MachineName » au paramètre ComputerName obligatoire.

        Param
          (
            [parameter(Mandatory=$true)]
            [alias("CN","MachineName")]
            [String[]]
            $ComputerName
          )

ATTRIBUTS DE VALIDATION DE PARAMÈTRES ET DE VARIABLES

Les attributs de validation chargent Windows PowerShell de tester les valeurs de paramètre envoyées par les utilisateurs quand ils appellent la fonction avancée. Si les valeurs de paramètre échouent au test, une erreur est générée et la fonction n'est pas appelée. Vous pouvez également utiliser certains des attributs de validation pour limiter les valeurs que les utilisateurs peuvent spécifier pour les variables.

Attribut de validation AllowNull

L'attribut AllowNull permet à la valeur d'un paramètre obligatoire d'être null ($null). L'exemple suivant déclare un paramètre ComputerName qui peut avoir une valeur Null.

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowNull()]
            [String]
            $ComputerName
          )

Attribut de validation AllowEmptyString

L'attribut AllowEmptyString permet à la valeur d'un paramètre obligatoire d'être une chaîne vide (""). L'exemple suivant déclare un paramètre ComputerName qui peut avoir une valeur de chaîne vide.

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowEmptyString()]
            [String]
            $ComputerName
          )

Attribut de validation AllowEmptyCollection

L'attribut AllowEmptyCollection permet à la valeur d'un paramètre obligatoire d'être une collection vide (@()). L'exemple suivant déclare un paramètre ComputerName qui peut avoir une valeur de collection vide.

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowEmptyCollection()]
            [String[]]
            $ComputerName
          )

Attribut de validation ValidateCount

L'attribut ValidateCount spécifie les nombres minimal et maximal de valeurs de paramètre qu'un paramètre accepte. Windows PowerShell génère une erreur si le nombre de valeurs de paramètre dans la commande qui appelle la fonction est en dehors de cette plage.

La déclaration de paramètre suivante crée un paramètre ComputerName qui accepte les valeurs de paramètre de 1 à 5.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateCount(1,5)]
            [String[]]
            $ComputerName
          )

Attribut de validation ValidateLength

L'attribut ValidateLength spécifie les nombres minimal et maximal de caractères dans une valeur de paramètre ou de variable. Windows PowerShell génère une erreur si la longueur d'une valeur spécifiée pour un paramètre ou une variable est en dehors de la plage.

Dans l'exemple suivant, chaque nom d'ordinateur doit comprendre entre un et 10 caractères.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateLength(1,10)]
            [String[]]
            $ComputerName
          )

Dans l'exemple suivant, la valeur de la variable $number doit être composée au minimum d'un caractère et au maximum de dix caractères en longueur.

        [Int32][ValidateLength(1,10)]$number = 01

Attribut de validation ValidatePattern

L'attribut ValidatePattern spécifie une expression régulière qui est comparée à la valeur de paramètre ou de variable. Windows PowerShell génère une erreur si la valeur ne correspond pas au modèle d'expression régulière.

Dans l'exemple suivant, la valeur de paramètre doit être un nombre à quatre chiffres, et chaque chiffre doit être un nombre compris entre 0 et 9.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidatePattern("[0-9][0-9][0-9][0-9]")]
            [String[]]
            $ComputerName
          )

Dans l'exemple suivant, la valeur de la variable $number doit être un nombre à quatre chiffres, et chaque chiffre doit être un nombre compris entre 0 et 9.

        [Int32][ValidatePattern("[0-9][0-9][0-9][0-9]")]$number = 1111

Attribut de validation ValidateRange

L'attribut ValidateRange spécifie une plage numérique pour chaque valeur de paramètre ou de variable. Windows PowerShell génère une erreur si une valeur est en dehors de cette plage. Dans l'exemple suivant, la valeur du paramètre Attempts doit être comprise entre 0 et 10.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateRange(0,10)]
            [Int]
            $Attempts
          )

Dans l'exemple suivant, la valeur de la variable $number doit être comprise entre 0 et 10.

        [Int32][ValidateRange(0,10)]$number = 5

Attribut de validation ValidateScript

L'attribut ValidateScript spécifie un script qui est utilisé pour valider une valeur de paramètre ou de variable. Windows PowerShell dirige la valeur vers le script, puis génère une erreur si le script retourne « false » ou lève une exception.

Quand vous utilisez l'attribut ValidateScript, la valeur en cours de validation est mappée à la variable $_. Vous pouvez utiliser la variable $_ pour faire référence à la valeur dans le script.

Dans l'exemple suivant, la valeur du paramètre EventDate doit être supérieure ou égale à la date actuelle.

        Param
          (
            [parameter()]
            [ValidateScript({$_ -ge (get-date)})]
            [DateTime]
            $EventDate
          )

Dans l'exemple suivant, la valeur de la variable $date doit être supérieure ou égale aux date et heure actuelles.

       [DateTime][ValidateScript({$_ -ge (get-date)})]$date = (get-date)

Attribut ValidateSet

L'attribut ValidateSet spécifie un jeu de valeurs valides pour un paramètre ou une variable. Windows PowerShell génère une erreur si une valeur de paramètre ou de variable ne correspond à aucune valeur du jeu. Dans l'exemple suivant, la valeur du paramètre Detail peut uniquement être « Low », « Average » ou « High ».

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateSet("Low", "Average", "High")]
            [String[]]
            $Detail
          )

Dans l'exemple suivant, la valeur de la variable $flavor doit être Chocolate, Strawberry ou Vanilla.

        [String][ValidateSet("Chocolate", "Strawberry", "Vanilla")]$flavor = Strawberry

Attribut de validation ValidateNotNull

L'attribut ValidateNotNull indique que la valeur de paramètre ne peut pas être null ($null). Windows PowerShell génère une erreur si la valeur de paramètre est null.

L'attribut ValidateNotNull est conçu pour être utilisé quand le type de la valeur de paramètre n'est pas spécifié ou que le type spécifié accepte la valeur Null. (Si vous spécifiez un type qui n'accepte pas de valeur null, comme une chaîne, la valeur null est rejetée sans l'attribut ValidateNotNull, car il ne correspond pas au type spécifié.)

Dans l'exemple suivant, la valeur du paramètre ID ne peut pas être null.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNull()]
            $ID
          )

Attribut de validation ValidateNotNullOrEmpty

L'attribut ValidateNotNullOrEmpty spécifie que la valeur de paramètre ne peut pas être null ($null) et ne peut pas être une chaîne vide (""). Windows PowerShell génère une erreur si le paramètre est utilisé dans un appel de fonction, mais que sa valeur est null, une chaîne vide ou un tableau vide.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNullOrEmpty()]
            [String[]]
            $UserName
          )

PARAMÈTRES DYNAMIQUES

Les paramètres dynamiques sont les paramètres d'une applet de commande, d'une fonction ou d'un script qui ne sont disponibles que sous certaines conditions.

Par exemple, plusieurs applets de commande fournisseur ont des paramètres qui sont disponibles uniquement quand l'applet de commande est utilisée dans le lecteur fournisseur ou dans un chemin d'accès particulier du lecteur fournisseur. Par exemple, le paramètre Encoding est disponible dans les applets de commande Add-Content, Get-Content et Set-Content uniquement pour une utilisation dans un lecteur de système de fichiers.

Vous pouvez également créer un paramètre qui s'affiche uniquement quand un autre paramètre est utilisé dans la commande de fonction ou a une certaine valeur.

Les paramètres dynamiques peuvent être très utiles, mais utilisez-les uniquement si nécessaire, car ils peuvent être difficiles à détecter pour les utilisateurs. Pour trouver un paramètre dynamique, l'utilisateur doit se situer dans le chemin d'accès fournisseur, utiliser le paramètre ArgumentList de l'applet de commande Get-Command ou utiliser le paramètre Path de Get-Help.

Pour créer un paramètre dynamique pour une fonction ou un script, utilisez le mot clé DynamicParam.

La syntaxe est la suivante :

      DynamicParam {<statement-list>}

Dans la liste des instructions, utilisez une instruction If pour spécifier les conditions dans lesquelles le paramètre est disponible dans la fonction.

Utilisez l'applet de commande New-Object pour créer un objet System.Management.Automation.RuntimeDefinedParameter pour représenter le paramètre et spécifier son nom.

Vous pouvez également utiliser une commande New-Object pour créer un objet System.Management.Automation.ParameterAttribute pour représenter les attributs du paramètre, tels que Mandatory, Position ou ValueFromPipeline, ou son jeu de paramètres.

L'exemple suivant montre un exemple de fonction avec des paramètres standard nommés Name et Path ainsi qu'un paramètre dynamique facultatif nommé DP1. Le paramètre DP1 est dans le jeu de paramètres PSet1 et de type Int32. Le paramètre DP1 est disponible dans l'exemple de fonction uniquement quand la valeur du paramètre Path contient « HKLM: », ce qui indique son utilisation dans le lecteur de Registre HKEY_LOCAL_MACHINE.

    function Get-Sample {
        [CmdletBinding()]
        Param ([String]$Name, [String]$Path)
 
        DynamicParam
        {
            if ($path -match ".*HKLM.*:")
            {
                $attributes = new-object System.Management.Automation.ParameterAttribute
                $attributes.ParameterSetName = "__AllParameterSets"
                $attributes.Mandatory = $false
                $attributeCollection = new-object `
                    -Type System.Collections.ObjectModel.Collection[System.Attribute]
                $attributeCollection.Add($attributes)

                $dynParam1 = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection)
            
                $paramDictionary = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameterDictionary
                $paramDictionary.Add("dp1", $dynParam1)
                return $paramDictionary
            }
        }
    }

Pour plus d'informations, consultez « RuntimeDefinedParameter, classe » dans MSDN (Microsoft Developer Network) Library à l'adresse https://go.microsoft.com/fwlink/?LinkID=145130.

Paramètres de commutateur

Les paramètres de commutateur sont des paramètres sans valeur de paramètre. Ils sont effectifs uniquement quand ils sont utilisés et n'ont qu'un seul effet.

Par exemple, le paramètre -NoProfile de PowerShell.exe est un paramètre de commutateur.

Pour créer un paramètre de commutateur dans une fonction, spécifiez le type Switch dans la définition de paramètre.

    For example:
        Param ([Switch]<ParameterName>)
    -or- 
        Param
          (
             [parameter(Mandatory=$false)]
             [Switch]
             $<ParameterName>
          )

Les paramètres de commutateur sont faciles à utiliser et sont préférés aux paramètres booléens, qui ont une syntaxe plus difficile.

Par exemple, pour utiliser un paramètre de commutateur, l'utilisateur tape le paramètre dans la commande.

        -IncludeAll

Pour utiliser un paramètre booléen, l'utilisateur tape le paramètre et une valeur booléenne.

        -IncludeAll:$true

Quand vous créez des paramètres de commutateur, choisissez avec soin le nom du paramètre. Assurez-vous que le nom du paramètre communique l'effet du paramètre à l'utilisateur et évitez les termes ambigus, tels que Filter ou Maximum, qui peuvent impliquer qu'une valeur est requise.

VOIR AUSSI

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute