RUBRIQUE
    about_Functions_Advanced_Parameters

DESCRIPTION COURTE
    Explique comment ajouter des paramètres statiques et dynamique aux 
    fonctions qui déclarent l'attribut CmdletBinding.

DESCRIPTION LONGUE
    Vous pouvez déclarer vos propres paramètres lorsque vous écrivez des 
    fonctions, et vous pouvez écrire des fonctions pour qu'elles puissent 
    accéder aux paramètres courants, disponibles pour les applets de 
    commande compilées. Pour plus d'informations sur les paramètres 
    courants Windows PowerShell, consultez about_CommonParameters.


Paramètres statiques

    L'exemple suivant présente une déclaration de paramètre qui définit un 
    paramètre ComputerName. Ce paramètre a les caractéristiques suivantes :

        - Il est obligatoire.
        - Il accepte l'entrée du pipeline.
        - Il accepte un tableau de chaînes comme entrée.

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

    Le seul attribut obligatoire à utiliser lorsque vous déclarez un 
    paramètre est l'attribut Parameter. Toutefois, vous pouvez également 
    déclarer l'attribut Alias et plusieurs arguments de validation. Le nombre 
    d'attributs que vous pouvez ajouter à une déclaration de paramètre 
    est illimité.


  Attribut Parameter

      L'attribut Parameter est utilisé pour déclarer un paramètre de 
      la fonction. Cet attribut comporte les arguments nommés suivants, 
      utilisés pour définir les caractéristiques du paramètre, 
      par exemple pour savoir s'il est obligatoire ou optionnel.


    Argument nommé Mandatory

        L'argument Mandatory indique que le paramètre est obligatoire 
        lorsque la fonction est exécutée. Si cet argument n'est pas 
        spécifié, le paramètre est un paramètre optionnel. L'exemple 
        suivant présente la déclaration d'un paramètre obligatoire 
        lorsque la fonction est exécutée.

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


    Argument nommé Position

        L'argument Position spécifie la position du paramètre. Si cet 
        argument n'est pas spécifié, le nom de paramètre ou son alias 
        doit être spécifié explicitement quand le paramètre est 
        défini. De même, si aucun des paramètres d'une fonction n'a 
        de position, le runtime Windows PowerShell affecte des positions 
        à chaque paramètre selon l'ordre dans lequel ils sont reçus. 

        L'exemple suivant présente la déclaration d'un paramètre dont 
        la valeur doit être spécifiée comme premier argument lorsque 
        l'applet de commande est exécutée. Notez que cette fonction 
        pourrait être exécutée avec ou sans spécification du nom du 
        paramètre.

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


    Argument nommé ParameterSetName

        L'argument ParameterSetName spécifie le jeu de paramètres 
        auquel un paramètre appartient. 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. Ce comportement signifie que chaque jeu de 
        paramètres doit avoir un paramètre unique qui n'est membre d'aucun 
        autre jeu de paramètres. L'exemple suivant présente la déclaration de 
        paramètre de deux paramètres qui appartiennent à deux jeux de 
        paramètres différents. 

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

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

        Pour plus d'informations sur les jeux de paramètres, 
        consultez " Cmdlet Parameter Sets " (page éventuellement 
        en anglais) dans la bibliothèque MSDN à l'adresse 
        https://go.microsoft.com/fwlink/?LinkId=142183.


    Argument nommé ValueFromPipeline

        L'argument ValueFromPipeline spécifie que le paramètre 
        accepte l'entrée provenant d'un objet de pipeline. Spécifiez cet 
        argument si l'applet de commande accède à l'objet complet et pas 
        seulement à une propriété de l'objet. L'exemple suivant présente 
        la déclaration de paramètre d'un paramètre ComputerName obligatoire 
        qui accepte l'objet d'entrée passé à la fonction à partir du pipeline.

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


    Argument nommé ValueFromPipelineByPropertyName

        L'argument valueFromPipelineByPropertyName spécifie que le 
        paramètre accepte l'entrée provenant d'une propriété d'un objet de 
        pipeline. Spécifiez cet attribut si les conditions suivantes sont 
        remplies :

            - Le paramètre accède à une propriété de l'objet redirigé.

            - La propriété porte le même nom que le paramètre, ou la 
              propriété a le même alias que le paramètre.

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

        L'exemple suivant présente la déclaration de paramètre d'un 
        paramètre ComputerName qui accepte l'entrée provenant de la 
        propriété ComputerName de l'objet d'entrée passé à l'applet 
        de commande.

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


    Argument nommé ValueFromRemainingArguments

        L'argument ValueFromRemainingArguments spécifie que le 
        paramètre accepte tous les arguments restants qui ne sont pas 
        liés aux paramètres de la fonction. L'exemple suivant présente la 
        déclaration de paramètre d'un paramètre ComputerName qui accepte 
        tous les arguments restants de l'objet d'entrée passé à la fonction.

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


    Argument nommé HelpMessage

        L'argument HelpMessage spécifie un message qui contient une 
        description courte du paramètre. L'exemple suivant présente une 
        déclaration de paramètre qui fournit une description du paramètre.

        Param
          (
            [parameter(Mandatory=$true,
                      HelpMessage="Un tableau de noms d'ordinateurs.")] 
            [String[]]
            $ComputerName
          ) 


  Attribut Alias

      L'attribut Alias spécifie un autre nom pour le paramètre. Le nombre 
      d'alias qui peuvent être affectés à un paramètre est illimité. 
      L'exemple suivant présente une déclaration de paramètre obligatoire 
      qui ajoute l'alias " CN " au paramètre ComputerName.

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


  Attributs de validation de paramètres

      Ces attributs définissent la façon dont le runtime Windows 
      PowerShell valide les arguments des fonctions avancées.


    Attribut de validation AllowNull

        L'attribut AllowNull autorise l'argument d'un paramètre 
        d'applet de commande obligatoire à être défini sur Null. 
        Dans l'exemple suivant, le paramètre ComputerName peut  
        contenir une valeur Null bien que ce paramètre soit un 
        paramètre obligatoire. 

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


    Attribut de validation AllowEmptyString

        L'attribut AllowEmptyString autorise une chaîne vide comme 
        argument d'un paramètre d'applet de commande obligatoire. 
        Dans l'exemple suivant, le paramètre ComputerName peut 
        contenir une chaîne vide ("") bien que ce paramètre soit 
        un paramètre obligatoire. 

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


    Attribut de validation AllowEmptyCollection

        L'attribut AllowEmptyCollection autorise une collection vide comme 
        argument d'un paramètre obligatoire. 

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


    Attribut de validation ValidateCount

        L'attribut ValidateCount spécifie le nombre minimal et le 
        nombre maximal d'arguments que le paramètre peut accepter. 
        Le runtime Windows PowerShell génère une erreur si le nombre 
        d'arguments se trouve à l'extérieur de cette plage. Dans l'exemple 
        suivant, le paramètre ComputerName peut avoir un à cinq arguments. 

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


    Attribut de validation ValidateLength

        L'attribut ValidateLength spécifie la longueur minimale et la 
        longueur maximale de l'argument de paramètre. Le runtime Windows 
        PowerShell génère une erreur si la longueur de l'argument de 
        paramètre se trouve à l'extérieur de cette plage. Dans l'exemple 
        suivant, les noms d'ordinateur spécifiés doivent 
        comporter un à 10 caractères. 

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


    Attribut de validation ValidatePattern

        L'attribut ValidatePattern spécifie une expression régulière 
        qui valide le modèle de l'argument de paramètre. Le runtime 
        Windows PowerShell génère une erreur si l'argument de paramètre 
        ne correspond pas à ce modèle. Dans l'exemple suivant, 
        l'argument du paramètre doit être un nombre à quatre chiffres. 

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


    Attribut de validation ValidateRange

        L'attribut ValidateRange spécifie les valeurs minimale et 
        maximale de l'argument de paramètre. Le runtime Windows PowerShell 
        génère une erreur si l'argument de paramètre se trouve à l'extérieur 
        de cette plage. Dans l'exemple suivant, l'argument du paramètre ne 
        peut pas être inférieur à 0, ni supérieur à 10. 


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


    Attribut de validation ValidateScript

        L'attribut ValidateScript spécifie un script utilisé pour valider 
        l'argument de paramètre. Le runtime Windows PowerShell génère une 
        erreur si le résultat de script est faux ou si le script lève une 
        exception. Dans l'exemple suivant, la valeur du paramètre Count 
        doit être inférieure à 4.

        Param
          (
            [parameter()]
            [Int]
            [ValidateScript({$_ -lt 4})]
            $Count
          ) 


    Attribut ValidateSet

        L'attribut ValidateSet spécifie un jeu de valeurs valides pour 
        l'argument du paramètre. Le runtime Windows PowerShell génère une 
        erreur si l'argument de paramètre ne correspond pas à une valeur 
        de ce jeu. Dans l'exemple suivant, l'argument du paramètre peut 
        uniquement contenir les prénoms Sylvain, Marie et Carl. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateRange("Sylvain", "Marie", "Carl")] 
            $UserName
          ) 


    Attribut de validation ValidateNotNull


        L'attribut ValidateNotNull spécifie que l'argument du 
        paramètre ne peut pas être défini sur Null. Le runtime Windows 
        PowerShell génère une erreur si la valeur de paramètre est Null.  

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


    Attribut de validation ValidateNotNullOrEmpty

        L'attribut ValidateNotNullOrEmpty spécifie que l'argument du 
        paramètre ne peut pas être défini sur Null ou ne peut pas 
        être vide. Le runtime Windows PowerShell génère une erreur 
        si le paramètre est spécifié, mais que sa valeur est Null, 
        une chaîne vide ou un tableau vide.  

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


Paramètres dynamiques
    Les paramètres dynamiques sont des paramètres d'une applet de commande, 
    d'une fonction ou d'un script disponibles uniquement dans certaines 
    conditions.

    Par exemple, plusieurs applets de commande de fournisseur ont des 
    paramètres disponibles uniquement lorsque l'applet de commande est 
    utilisée dans le chemin d'accès du fournisseur.Un paramètre dynamique 
    connu est le paramètre Encoding de l'applet de commande Set-Item, qui 
    est uniquement disponible lorsque l'applet de commande Set-Item est 
    utilisée dans un chemin d'accès de fournisseur FileSystem. 

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

      DynamicParam {<liste-instructions>}

    Dans la liste d'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 appelés Name et Path, ainsi qu'un paramètre dynamique facultatif 
    nommé DP1. Le paramètre DP1 parameter est dans le jeu de paramètres PSet1 
    et est de type Int32. Le paramètre DP1 est disponible dans l'exemple de 
    fonction uniquement lorsque la valeur du paramètre Path contient "HKLM:", 
    indiquant qu'il est en cours d'utilisation dans le lecteur de Registre 
    HKEY_LOCAL_MACHINE. 

    function Sample { 
      Param ([String]$Name, [String]$Path)

      DynamicParam 
      {
        if ($path -match "*HKLM*:") 
        {
          $dynParam1 = new-object  
            System.Management.Automation.RuntimeDefinedParameter("dp1",
            [Int32], $attributeCollection) 

          $attributes = new-object System.Management.Automation.ParameterAttribute 
          $attributes.ParameterSetName = 'pset1' 
          $attributes.Mandatory = $false 
          $attributeCollection = new-object 
            -Type System.Collections.ObjectModel.Collection``1[System.Attribute] 
          $attributeCollection.Add($attributes)

          $paramDictionary = new-object  
            System.Management.Automation.RuntimeDefinedParameterDictionary 
          $paramDictionary.Add("dp1", $dynParam1) 

          return $paramDictionary 
        } End if 
      }
    }

    Pour plus d'informations, consultez " RuntimeDefinedParameter Class " 
    (page éventuellement en anglais) dans la biblothèque MSDN (Microsoft Developer 
    Network) à l'adresse https://go.microsoft.com/fwlink/?LinkID=145130.


VOIR AUSSI
    Fonctions about_Advanced
    about_Functions_Advanced_Methods
    about_Functions_CmdletBindingAttributes  




Table des matières