about_Functions_Advanced_Parameters
Description courte
Explique comment ajouter des paramètres aux fonctions avancées.
Description longue
Vous pouvez ajouter des paramètres aux fonctions avancées que vous écrivez et utiliser des attributs de paramètre et des arguments pour limiter les valeurs de paramètre que les utilisateurs de fonction envoient avec le paramètre.
Les paramètres que vous ajoutez à votre fonction sont disponibles pour les utilisateurs en plus des paramètres courants que PowerShell ajoute automatiquement à toutes les applets de commande et fonctions avancées. Pour plus d’informations sur les paramètres courants de PowerShell, consultez about_CommonParameters.
À partir de PowerShell 3.0, vous pouvez utiliser splatting avec @Args pour représenter les paramètres dans une commande. La platetage est valide sur les fonctions simples et avancées. Pour plus d’informations, consultez about_Functions et about_Splatting.
Conversion de type des valeurs de paramètres
Lorsque vous fournissez des chaînes en tant qu’arguments à des paramètres qui attendent un type différent, PowerShell convertit implicitement les chaînes en type cible de paramètre. Les fonctions avancées effectuent l’analyse invariante de culture des valeurs de paramètre.
En revanche, une conversion sensible à la culture est effectuée lors de la liaison de paramètres pour les applets de commande compilées.
Dans cet exemple, nous créons une applet de commande et une fonction de script qui prennent un [datetime] paramètre. La culture actuelle est modifiée pour utiliser les paramètres allemands.
Une date au format allemand est passée au paramètre.
# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
using System;
using System.Management.Automation;
[Cmdlet("Get", "Date_Cmdlet")]
public class GetFooCmdlet : Cmdlet {
[Parameter(Position=0)]
public DateTime Date { get; set; }
protected override void ProcessRecord() {
WriteObject(Date);
}
}
'@ -PassThru | % Assembly | Import-Module
[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'
Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00
Comme indiqué ci-dessus, les applets de commande utilisent l’analyse sensible à la culture pour convertir la chaîne.
# Define an equivalent function.
function Get-Date_Func {
param(
[DateTime] $Date
)
process {
$Date
}
}
[cultureinfo]::CurrentCulture = 'de-DE'
# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'
Get-Date_Func $dateStr
Les fonctions avancées utilisent l’analyse invariante de culture, ce qui entraîne l’erreur suivante.
Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error: "String
'19-06-2018' was not recognized as a valid DateTime."
Paramètres statiques
Les paramètres statiques sont des paramètres qui sont toujours disponibles dans la fonction . La plupart des paramètres des applets de commande et des scripts PowerShell sont des paramètres statiques.
L’exemple suivant montre la déclaration d’un paramètre ComputerName qui présente les caractéristiques suivantes :
- Il est obligatoire (obligatoire).
- Il prend une entrée à partir du pipeline.
- Il prend un tableau de chaînes comme entrée.
Param(
[Parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[string[]]
$ComputerName
)
Paramètres de commutateur
Les paramètres de commutateur sont des paramètres qui ne prennent aucune valeur de paramètre. Au lieu de cela, ils transmettent une valeur booléenne true ou false par le biais de leur présence ou de leur absence, de sorte que lorsqu’un paramètre de commutateur est présent, il a une valeur true et lorsqu’il est absent, il a une valeur false .
Par exemple, le paramètre Recurse de Get-ChildItem est un paramètre switch.
Pour créer un paramètre switch dans une fonction, spécifiez le switch type dans la définition de paramètre.
Par exemple, votre fonction peut avoir la possibilité de générer des données en tant que tableau d’octets :
Param([switch]$AsByteArray)
Les paramètres de commutateur sont faciles à utiliser et sont préférés aux paramètres booléens, qui ont une syntaxe moins naturelle pour PowerShell.
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
Lorsque vous créez des paramètres de commutateur, choisissez soigneusement le nom du paramètre. Assurez-vous que le nom du paramètre communique l’effet du paramètre à l’utilisateur. Évitez les termes ambigus, tels que Filtre ou Maximum , qui peuvent impliquer qu’une valeur est requise.
Considérations relatives à la conception des paramètres de commutateur
Les paramètres de commutateur ne doivent pas recevoir de valeurs par défaut. Ils doivent toujours avoir la valeur false par défaut.
Les paramètres de commutateur sont exclus des paramètres positionnels par défaut. Même si d’autres paramètres sont implicitement positionnels, les paramètres de commutateur ne le sont pas. Vous pouvez remplacer cela dans l’attribut Parameter, mais cela va embrouiller les utilisateurs.
Les paramètres de commutateur doivent être conçus de telle sorte que leur définition déplace une commande de ses fonctionnalités par défaut vers un mode moins courant ou plus complexe. Le comportement le plus simple d’une commande doit être le comportement par défaut qui ne nécessite pas l’utilisation de paramètres de commutateur.
Les paramètres de commutateur ne doivent pas être obligatoires. Le seul cas où il est nécessaire de rendre obligatoire un paramètre de commutateur est quand il est nécessaire de différencier un jeu de paramètres.
La définition explicite d’un commutateur à partir d’un booléen peut être effectuée avec
-MySwitch:$boolValueet dans la mise en plaques avec$params = @{ MySwitch = $boolValue }.Les paramètres de commutateur sont de type
SwitchParameter, qui convertit implicitement en booléen. La variable de paramètre peut être utilisée directement dans une expression conditionnelle. Par exemple :if ($MySwitch) { ... }Il n’est pas nécessaire d’écrire
if ($MySwitch.IsPresent) { ... }
Paramètres dynamiques
Les paramètres dynamiques sont des paramètres d’une applet de commande, d’une fonction ou d’un script qui sont disponibles uniquement dans certaines conditions.
Par exemple, plusieurs applets de commande de fournisseur ont des paramètres qui sont disponibles uniquement lorsque l’applet de commande est utilisée dans le lecteur du fournisseur ou dans un chemin d’accès particulier du lecteur du fournisseur. Par exemple, le paramètre Encoding est disponible sur les Add-Contentapplets de commande , Get-Contentet Set-Content uniquement lorsqu’il est utilisé dans un lecteur de système de fichiers.
Vous pouvez également créer un paramètre qui apparaît uniquement lorsqu’un autre paramètre est utilisé dans la commande de fonction ou lorsqu’un autre paramètre a une certaine valeur.
Les paramètres dynamiques peuvent être utiles, mais les utiliser uniquement si nécessaire, car ils peuvent être difficiles à découvrir pour les utilisateurs. Pour rechercher un paramètre dynamique, l’utilisateur doit se trouver dans le chemin du fournisseur, utiliser le paramètre ArgumentList de l’applet Get-Command de commande ou utiliser le paramètre Path de Get-Help.
Pour créer un paramètre dynamique pour une fonction ou un script, utilisez le DynamicParam mot clé.
La syntaxe est la suivante :
dynamicparam {<statement-list>}
Dans la liste des instructions, utilisez une if instruction pour spécifier les conditions dans lesquelles le paramètre est disponible dans la fonction .
L’exemple suivant montre une fonction avec des paramètres standard nommés Name et Path, et un paramètre dynamique facultatif nommé KeyCount. Le paramètre KeyCount se trouve dans l’ensemble de ByRegistryPath paramètres et a un type de Int32. Le paramètre KeyCount est disponible dans la Get-Sample fonction uniquement lorsque la valeur du paramètre Path commence par HKLM:, ce qui indique qu’il est utilisé dans le lecteur du HKEY_LOCAL_MACHINE Registre.
function Get-Sample {
[CmdletBinding()]
Param([string]$Name, [string]$Path)
DynamicParam
{
if ($Path.StartsWith("HKLM:"))
{
$parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
ParameterSetName = "ByRegistryPath"
Mandatory = $false
}
$attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
$attributeCollection.Add($parameterAttribute)
$dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
'KeyCount', [Int32], $attributeCollection
)
$paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
$paramDictionary.Add('KeyCount', $dynParam1)
return $paramDictionary
}
}
}
Pour plus d’informations, consultez la documentation relative au type RuntimeDefinedParameter .
Attributs des 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 , pour être reconnu comme une fonction avancée, la fonction doit inclure l’attribut Parameter .
Vous pouvez ajouter un ou plusieurs attributs dans 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 de paramètre
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 n’a besoin d’attributs. Toutefois, pour être reconnue comme une fonction avancée plutôt que comme une fonction simple, une fonction doit avoir l’attribut CmdletBinding ou l’attribut Parameter , ou les deux.
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)]
)
Les types d’arguments booléens de l’attribut Parameter par défaut ont la valeur False en cas d’omission de l’attribut Parameter . Définissez la valeur de l’argument sur $true ou répertoriez simplement l’argument par nom. Par exemple, les attributs parameter suivants sont équivalents.
Param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
Param(
[Parameter(Mandatory)]
)
Si vous utilisez l’attribut Parameter sans arguments, comme alternative à l’utilisation de l’attribut CmdletBinding , les parenthèses qui suivent le nom de l’attribut sont toujours requises.
Param(
[Parameter()]
$ParameterName
)
Argument obligatoire
L’argument Mandatory indique que le paramètre est obligatoire. Si cet argument n’est pas spécifié, le paramètre est facultatif.
L’exemple suivant déclare le paramètre ComputerName . Il utilise l’argument Mandatory pour rendre le paramètre obligatoire.
Param(
[Parameter(Mandatory)]
[string[]]
$ComputerName
)
Argument position
L’argument Position détermine si le nom du paramètre est requis lorsque le paramètre est utilisé dans une commande. Lorsqu’une déclaration de paramètre inclut l’argument Position , le nom du paramètre peut être omis et PowerShell identifie la valeur de paramètre sans nom par sa position, ou son ordre, dans la liste des valeurs de paramètre sans nom dans la commande.
Si l’argument Position n’est pas spécifié, le nom du paramètre, ou un alias ou une abréviation de nom de paramètre, doit précéder la valeur du paramètre chaque fois que le paramètre est utilisé dans une commande.
Par défaut, tous les paramètres de fonction sont positionnels. PowerShell affecte des numéros de position aux paramètres dans l’ordre dans lequel les paramètres sont déclarés dans la fonction. Pour désactiver cette fonctionnalité, définissez la valeur de l’argument PositionalBinding de l’attribut CmdletBinding sur $False. L’argument Position est prioritaire sur la valeur de l’argument PositionalBinding de l’attribut CmdletBinding . Pour plus d’informations, consultez PositionalBinding dans about_Functions_CmdletBindingAttribute.
La valeur de l’argument Position est spécifiée sous forme d’entier. Une valeur de position de 0 représente la première position de la commande, une valeur de position de 1 représente la deuxième position de la commande, et ainsi de suite.
Si une fonction n’a pas de paramètres positionnels, PowerShell affecte des positions à chaque paramètre en fonction de l’ordre dans lequel les paramètres sont déclarés.
Toutefois, comme bonne pratique, ne vous fiez pas à cette affectation. Lorsque 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
)
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 ensembles de paramètres définis par la fonction . Par conséquent, pour être unique, chaque jeu de paramètres doit avoir au moins un paramètre qui n’est pas membre d’un autre ensemble de paramètres.
Notes
Pour une applet de commande ou une fonction, il existe une limite de 32 ensembles de paramètres.
L’exemple suivant déclare un paramètre ComputerName dans le jeu de Computer paramètres, un paramètre UserName dans le User jeu de paramètres et un paramètre Summary dans les deux ensembles de paramètres.
Param(
[Parameter(Mandatory,
ParameterSetName="Computer")]
[string[]]
$ComputerName,
[Parameter(Mandatory,
ParameterSetName="User")]
[string[]]
$UserName,
[Parameter()]
[switch]
$Summary
)
Vous ne pouvez spécifier qu’une ParameterSetName seule valeur dans chaque argument et un ParameterSetName seul argument dans chaque attribut Parameter . Pour indiquer qu’un paramètre apparaît dans plusieurs ensembles de paramètres, ajoutez des attributs parameter supplémentaires.
L’exemple suivant ajoute explicitement le paramètre Summary aux jeux de Computer paramètres et User . Le paramètre Summary est facultatif dans le jeu de Computer paramètres et obligatoire dans le jeu de User paramètres.
Param(
[Parameter(Mandatory,
ParameterSetName="Computer")]
[string[]]
$ComputerName,
[Parameter(Mandatory,
ParameterSetName="User")]
[string[]]
$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, ParameterSetName="User")]
[switch]
$Summary
)
Pour plus d’informations sur les ensembles de paramètres, consultez À propos des ensembles de paramètres.
Argument ValueFromPipeline
L’argument ValueFromPipeline indique que le paramètre accepte l’entrée d’un objet pipeline. Spécifiez cet argument si la fonction accepte l’objet entier, pas seulement une propriété de l’objet.
L’exemple suivant déclare un paramètre ComputerName obligatoire et accepte un objet passé à la fonction à partir du pipeline.
Param(
[Parameter(Mandatory,
ValueFromPipeline)]
[string[]]
$ComputerName
)
Argument ValueFromPipelineByPropertyName
L’argument ValueFromPipelineByPropertyName indique que le paramètre accepte l’entrée d’une propriété d’un objet pipeline. La propriété object doit avoir le même nom ou alias que le paramètre.
Par exemple, si la fonction a un paramètre ComputerName et que l’objet canalé 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 obligatoire et accepte l’entrée de la propriété ComputerName de l’objet transmise à la fonction via le pipeline.
Param(
[Parameter(Mandatory,
ValueFromPipelineByPropertyName)]
[string[]]
$ComputerName
)
Notes
Un paramètre typé qui accepte l’entrée de pipeline (by Value) ou (by PropertyName) permet l’utilisation de blocs de script de liaison différée sur le paramètre.
Le bloc de script de liaison différée est exécuté automatiquement pendant ParameterBinding. Le résultat est lié au paramètre . La liaison différée ne fonctionne pas pour les paramètres définis comme type ScriptBlock ou System.Object. Le bloc de script est transmis sans être appelé.
Vous pouvez en savoir plus sur les blocs de script delay-bind ici about_Script_Blocks.md.
Argument ValueFromRemainingArguments
L’argument ValueFromRemainingArguments indique que le paramètre accepte toutes les valeurs du paramètre dans la commande qui ne sont pas affectées à d’autres paramètres de la fonction.
L’exemple suivant déclare un paramètre Value obligatoire et un paramètre Restant qui accepte toutes les valeurs de paramètre restantes soumises à la fonction.
function Test-Remainder
{
param(
[string]
[Parameter(Mandatory, Position=0)]
$Value,
[string[]]
[Parameter(Position=1, ValueFromRemainingArguments)]
$Remaining)
"Found $($Remaining.Count) elements"
for ($i = 0; $i -lt $Remaining.Count; $i++)
{
"${i}: $($Remaining[$i])"
}
}
Test-Remainder first one,two
Found 2 elements
0: one
1: two
Notes
Avant PowerShell 6.2, la collection ValueFromRemainingArguments était jointe en tant qu’entité unique sous l’index 0.
Argument HelpMessage
L’argument HelpMessage spécifie une chaîne qui contient une brève description du paramètre ou de sa valeur. PowerShell affiche ce message dans l’invite qui s’affiche lorsqu’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.
S’il n’existe aucune autre syntaxe d’aide basée sur les commentaires pour la fonction (par exemple, .SYNOPSIS) ce message s’affiche également dans la Get-Help sortie.
Param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]
$ComputerName
)
Alias (attribut)
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 montre une déclaration de paramètre qui ajoute les alias CN et MachineName au paramètre obligatoire ComputerName .
Param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]
$ComputerName
)
Attribut SupportsWildcards
L’attribut SupportsWildcards est utilisé pour indiquer que le paramètre accepte des valeurs génériques. L’exemple suivant montre une déclaration de paramètre pour un paramètre Path obligatoire qui prend en charge les valeurs génériques.
Param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]
$Path
)
L’utilisation de cet attribut n’active pas automatiquement la prise en charge de caractères génériques. Le développeur d’applets de commande doit implémenter le code pour gérer l’entrée générique. Les caractères génériques pris en charge peuvent varier en fonction de l’API sous-jacente ou du fournisseur PowerShell. Pour plus d’informations, consultez about_Wildcards.
Attributs de saisie semi-automatique d’argument
Attribut ArgumentCompletions
L’attribut ArgumentCompletions vous permet d’ajouter des valeurs d’achèvement de tabulation à un paramètre spécifique. Un attribut ArgumentCompletions doit être défini pour chaque paramètre qui a besoin d’une saisie semi-automatique de tabulation. L’attribut ArgumentCompletions est similaire à ValidateSet. Les deux attributs prennent une liste de valeurs à présenter lorsque l’utilisateur appuie sur Tab après le nom du paramètre. Toutefois, contrairement à ValidateSet, les valeurs ne sont pas validées.
Cet attribut a été introduit dans PowerShell 6.0.
Pour plus d’informations, consultez about_Functions_Argument_Completion.
Attribut ArgumentCompleter
L’attribut ArgumentCompleter vous permet d’ajouter des valeurs d’achèvement de tabulation à un paramètre spécifique. Un attribut ArgumentCompleter doit être défini pour chaque paramètre qui a besoin d’une saisie semi-automatique de tabulation. Comme pour DynamicParameters, les valeurs disponibles sont calculées au moment de l’exécution lorsque l’utilisateur appuie sur Tab après le nom du paramètre.
Pour plus d’informations, consultez about_Functions_Argument_Completion.
Attributs de validation des paramètres et des variables
Les attributs de validation dirigent PowerShell pour tester les valeurs de paramètre que les utilisateurs envoient lorsqu’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. La validation des paramètres est appliquée uniquement à l’entrée fournie et toutes les autres valeurs telles que les valeurs par défaut ne sont pas validées.
Vous pouvez également utiliser les attributs de validation pour restreindre les valeurs que les utilisateurs peuvent spécifier pour les variables. Lorsque vous utilisez un convertisseur de type avec un attribut de validation, le convertisseur de type doit être défini avant l’attribut.
[int32][AllowNull()] $number = 7
Notes
Les attributs de validation peuvent être appliqués à n’importe quelle variable, pas seulement aux paramètres. Vous pouvez définir la validation pour n’importe quelle variable dans un script.
Attribut de validation AllowNull
L’attribut AllowNull permet à la valeur d’un paramètre obligatoire d’être $null. L’exemple suivant déclare un paramètre ComputerInfo pouvant avoir une valeur null .
Param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]
$ComputerInfo
)
Notes
L’attribut AllowNull ne fonctionne pas si le convertisseur de type est défini sur string, car le type de chaîne n’accepte pas de valeur Null. Vous pouvez utiliser l’attribut AllowEmptyString pour ce scénario.
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)]
[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)]
[AllowEmptyCollection()]
[string[]]
$ComputerName
)
Attribut de validation ValidateCount
L’attribut ValidateCount spécifie le nombre minimal et maximal de valeurs de paramètre qu’un paramètre accepte. PowerShell génère une erreur si le nombre de valeurs de paramètre dans la commande qui appelle la fonction se trouve en dehors de cette plage.
La déclaration de paramètre suivante crée un paramètre ComputerName qui prend une à cinq valeurs de paramètre.
Param(
[Parameter(Mandatory)]
[ValidateCount(1,5)]
[string[]]
$ComputerName
)
Attribut de validation ValidateLength
L’attribut ValidateLength spécifie le nombre minimal et maximal de caractères dans un paramètre ou une valeur de variable. 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 comporter un à dix caractères.
Param(
[Parameter(Mandatory)]
[ValidateLength(1,10)]
[string[]]
$ComputerName
)
Dans l’exemple suivant, la valeur de la variable $number doit être d’au moins un caractère et d’un maximum de dix caractères.
[Int32][ValidateLength(1,10)]$number = '01'
Notes
Dans cet exemple, la valeur de 01 est encapsulée entre guillemets simples. L’attribut ValidateLength n’accepte pas un nombre sans être encapsulé entre guillemets.
Attribut de validation ValidatePattern
L’attribut ValidatePattern spécifie une expression régulière comparée au paramètre ou à la valeur de variable. 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 du paramètre doit contenir un nombre à quatre chiffres, et chaque chiffre doit être un nombre zéro à neuf.
Param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
[string[]]
$ComputerName
)
Dans l’exemple suivant, la valeur de la variable $number doit être exactement un nombre à quatre chiffres, et chaque chiffre doit être un nombre zéro à neuf.
[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 ou une valeur d’énumération ValidateRangeKind pour chaque paramètre ou valeur de variable. PowerShell génère une erreur si une valeur se trouve en dehors de cette plage.
L’énumération ValidateRangeKind autorise les valeurs suivantes :
- Positif : nombre supérieur à zéro.
- Négatif : nombre inférieur à zéro.
- NonPositive : nombre inférieur ou égal à zéro.
- NonNegative : nombre supérieur ou égal à zéro.
Dans l’exemple suivant, la valeur du paramètre Tentatives doit être comprise entre zéro et dix.
Param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[Int]
$Attempts
)
Dans l’exemple suivant, la valeur de la variable $number doit être comprise entre zéro et dix.
[Int32][ValidateRange(0,10)]$number = 5
Dans l’exemple suivant, la valeur de la variable $number doit être supérieure à zéro.
[Int32][ValidateRange("Positive")]$number = 1
Attribut de validation ValidateScript
L’attribut ValidateScript spécifie un script utilisé pour valider un paramètre ou une valeur de variable. PowerShell envoie la valeur au script et génère une erreur si le script retourne $false ou si le script lève une exception.
Lorsque 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(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]
$EventDate
)
Dans l’exemple suivant, la valeur de la variable $date doit être supérieure ou égale à la date et à l’heure actuelles.
[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)
Notes
Si vous utilisez ValidateScript, vous ne pouvez pas passer une $null valeur au paramètre . Lorsque vous transmettez une valeur Null , ValidateScript ne peut pas valider l’argument.
Attribut ValidateSet
L’attribut ValidateSet spécifie un ensemble de valeurs valides pour un paramètre ou une variable et active la saisie semi-automatique par tabulation. PowerShell génère une erreur si une valeur de paramètre ou de variable ne correspond pas à une valeur du jeu. Dans l’exemple suivant, la valeur du paramètre Detail ne peut être que Faible, Moyenne ou Élevée.
Param(
[Parameter(Mandatory)]
[ValidateSet("Low", "Average", "High")]
[string[]]
$Detail
)
Dans l’exemple suivant, la valeur de la variable $flavor doit être Chocolate, Strawberry ou Vanilla.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"
La validation se produit chaque fois que cette variable est affectée, même dans le script. Par exemple, les éléments suivants entraînent une erreur au moment de l’exécution :
Param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
Cet exemple retourne l’erreur suivante au moment de l’exécution :
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
L’utilisation ValidateSet de permet également l’extension de tabulation des valeurs pour ce paramètre. Pour plus d’informations, consultez about_Tab_Expansion.
Valeurs ValidateSet dynamiques utilisant des classes
Vous pouvez utiliser une classe pour générer dynamiquement les valeurs de ValidateSet au moment de l’exécution. Dans l’exemple suivant, les valeurs valides pour la variable $Sound sont générées via une classe nommée SoundNames qui vérifie trois chemins d’accès au système de fichiers pour les fichiers audio disponibles :
Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
[string[]] GetValidValues() {
$SoundPaths = '/System/Library/Sounds/',
'/Library/Sounds','~/Library/Sounds'
$SoundNames = ForEach ($SoundPath in $SoundPaths) {
If (Test-Path $SoundPath) {
(Get-ChildItem $SoundPath).BaseName
}
}
return [string[]] $SoundNames
}
}
La [SoundNames] classe est ensuite implémentée en tant que valeur ValidateSet dynamique comme suit :
Param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Notes
La IValidateSetValuesGenerator classe a été introduite dans PowerShell 6.0
Attribut de validation ValidateNotNull
L’attribut ValidateNotNull spécifie que la valeur du paramètre ne peut pas être $null. PowerShell génère une erreur si la valeur du paramètre est $null.
L’attribut ValidateNotNull est conçu pour être utilisé lorsque le paramètre est facultatif et que le type n’est pas défini ou a un convertisseur de type qui ne peut pas convertir implicitement une valeur Null comme un objet. Si vous spécifiez un type qui convertira implicitement une valeur Null telle qu’une chaîne, la valeur Null est convertie en chaîne vide même lors de l’utilisation de l’attribut ValidateNotNull . Pour ce scénario, utilisez ValidateNotNullOrEmpty
Dans l’exemple suivant, la valeur du paramètre ID ne peut pas être $null.
Param(
[Parameter()]
[ValidateNotNull()]
$ID
)
Attribut de validation ValidateNotNullOrEmpty
L’attribut ValidateNotNullOrEmpty spécifie que la valeur du paramètre ne peut pas être $null et ne peut pas être une chaîne vide (""). PowerShell génère une erreur si le paramètre est utilisé dans un appel de fonction, mais sa valeur est $null, une chaîne vide ("") ou un tableau @()vide .
Param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]
$UserName
)
Attribut de validation ValidateDrive
L’attribut ValidateDrive spécifie que la valeur du paramètre doit représenter le chemin d’accès, qui fait référence aux lecteurs autorisés uniquement. PowerShell génère une erreur si la valeur du paramètre fait référence à d’autres lecteurs que le autorisé. L’existence du chemin, à l’exception du lecteur lui-même, n’est pas vérifiée.
Si vous utilisez le chemin relatif, le lecteur actuel doit figurer dans la liste des lecteurs autorisés.
Param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
Attribut de validation ValidateUserDrive
L’attribut ValidateUserDrive spécifie que la valeur du paramètre doit représenter le chemin d’accès, qui fait référence au User lecteur. PowerShell génère une erreur si le chemin d’accès fait référence à un autre lecteur. L’attribut de validation teste uniquement l’existence de la partie lecteur du chemin.
Si vous utilisez le chemin relatif, le lecteur actuel doit être User.
function Test-UserDrivePath{
[OutputType([bool])]
Param(
[Parameter(Mandatory, Position=0)][ValidateUserDrive()][string]$Path
)
$True
}
Test-UserDrivePath -Path C:\
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.
Vous pouvez définir User le lecteur dans les configurations de session JeA (Just Enough Administration). Pour cet exemple, nous créons le lecteur User :.
New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH
Name Used (GB) Free (GB) Provider Root
---- --------- --------- -------- ----
User 75.76 24.24 FileSystem C:\Users\ExampleUser
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True
Attribut de validation ValidateTrustedData
Cet attribut a été ajouté dans PowerShell 6.1.1.
À ce stade, l’attribut est utilisé en interne par PowerShell lui-même et n’est pas destiné à une utilisation externe.