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