about_Parameter_Sets
Description courte
Décrit comment définir et utiliser des ensembles de paramètres dans des fonctions avancées.
Description longue
PowerShell utilise des ensembles de paramètres pour vous permettre d’écrire une fonction unique qui peut effectuer différentes actions pour différents scénarios. Les jeux de paramètres vous permettent d’exposer différents paramètres à l’utilisateur. Pour retourner différentes informations en fonction des paramètres spécifiés par l’utilisateur. Vous ne pouvez utiliser qu’un seul jeu de paramètres à la fois.
Configuration requise de l’ensemble de paramètres
Les exigences suivantes s’appliquent à tous les ensembles de paramètres.
Si aucun jeu de paramètres n’est spécifié pour un paramètre, le paramètre est membre de tous les jeux de paramètres.
Chaque jeu de paramètres doit avoir une combinaison unique de paramètres. Si possible, au moins un des paramètres uniques doit être un paramètre obligatoire.
Un jeu de paramètres qui contient plusieurs paramètres positionnels doit définir des positions uniques pour chaque paramètre. Deux paramètres positionnels ne peuvent pas spécifier la même position.
Un seul paramètre d’un jeu peut déclarer l’mot clé
ValueFromPipelineavec la valeurtrue. Plusieurs paramètres peuvent définir l’mot cléValueFromPipelineByPropertyNameavec une valeur detrue.
Remarque
Il existe une limite de 32 ensembles de paramètres.
Ensembles de paramètres par défaut
Lorsque plusieurs jeux de paramètres sont définis, l’mot clé DefaultParameterSetName de l’attribut CmdletBinding spécifie le jeu de paramètres par défaut.
PowerShell utilise le jeu de paramètres par défaut lorsqu’il ne peut pas déterminer le jeu de paramètres à utiliser en fonction des informations fournies à la commande. Pour plus d’informations sur l’attribut CmdletBinding , consultez about_Functions_CmdletBindingAttribute.
Déclaration des jeux de paramètres
Pour créer un jeu de paramètres, vous devez spécifier l’mot clé ParameterSetName de l’attribut Paramètre pour chaque paramètre du jeu de paramètres. Pour les paramètres appartenant à plusieurs jeux de paramètres, ajoutez un attribut Paramètre pour chaque jeu de paramètres.
L’attribut Paramètre vous permet de définir le paramètre différemment pour chaque jeu de paramètres. Par exemple, vous pouvez définir un paramètre comme obligatoire dans un ensemble et facultatif dans un autre. Toutefois, chaque jeu de paramètres doit contenir au moins un paramètre unique.
Les paramètres qui n’ont pas de nom de jeu de paramètres attribué appartiennent à tous les jeux de paramètres.
Exemples
L’exemple de fonction suivant compte les lignes numériques, les caractères et les mots dans un fichier texte. À l’aide de paramètres, vous pouvez spécifier les valeurs que vous souhaitez retourner et les fichiers que vous souhaitez mesurer. Il existe quatre jeux de paramètres définis :
- Chemin d’accès
- PathAll
- LittéralPath
- LiteralPathAll
function Measure-Lines {
[CmdletBinding(DefaultParameterSetName = 'Path')]
param (
[Parameter(Mandatory, ParameterSetName = 'Path', Position = 0)]
[Parameter(Mandatory, ParameterSetName = 'PathAll', Position = 0)]
[string[]]$Path,
[Parameter(Mandatory, ParameterSetName = 'LiteralPathAll', ValueFromPipeline)]
[Parameter(Mandatory, ParameterSetName = 'LiteralPath', ValueFromPipeline)]
[string[]]$LiteralPath,
[Parameter(ParameterSetName = 'Path')]
[Parameter(ParameterSetName = 'LiteralPath')]
[switch]$Lines,
[Parameter(ParameterSetName = 'Path')]
[Parameter(ParameterSetName = 'LiteralPath')]
[switch]$Words,
[Parameter(ParameterSetName = 'Path')]
[Parameter(ParameterSetName = 'LiteralPath')]
[switch]$Characters,
[Parameter(Mandatory, ParameterSetName = 'PathAll')]
[Parameter(Mandatory, ParameterSetName = 'LiteralPathAll')]
[switch]$All,
[Parameter(ParameterSetName = 'Path')]
[Parameter(ParameterSetName = 'PathAll')]
[switch]$Recurse
)
begin {
if ($All) {
$Lines = $Words = $Characters = $true
}
elseif (($Words -eq $false) -and ($Characters -eq $false)) {
$Lines = $true
}
}
process {
if ($Path) {
$Files = Get-ChildItem -Path $Path -Recurse:$Recurse -File
}
else {
$Files = Get-ChildItem -LiteralPath $LiteralPath -File
}
foreach ($file in $Files) {
$result = [ordered]@{ }
$result.Add('File', $file.fullname)
$content = Get-Content -LiteralPath $file.fullname
if ($Lines) { $result.Add('Lines', $content.Length) }
if ($Words) {
$wc = 0
foreach ($line in $content) { $wc += $line.split(' ').Length }
$result.Add('Words', $wc)
}
if ($Characters) {
$cc = 0
foreach ($line in $content) { $cc += $line.Length }
$result.Add('Characters', $cc)
}
New-Object -TypeName psobject -Property $result
}
}
}
Chaque jeu de paramètres doit avoir un paramètre unique ou une combinaison unique de paramètres. Les Path jeux de paramètres et PathAll les ensembles de paramètres sont très similaires, mais le paramètre All est unique au jeu de PathAll paramètres. Il en va de même avec les jeux de paramètres et LiteralPathAll les LiteralPath jeux de paramètres. Même si les ensembles de paramètres et les PathAll ensembles de paramètres ont tous deux le paramètre All, les paramètres Path et LiteralPath les différencientLiteralPathAll.
L’utilisation Get-Command -Syntax vous montre la syntaxe de chaque jeu de paramètres. Toutefois, il n’affiche pas le nom du jeu de paramètres. L’exemple suivant montre quels paramètres peuvent être utilisés dans chaque jeu de paramètres.
(Get-Command Measure-Lines).ParameterSets |
Select-Object -Property @{n='ParameterSetName';e={$_.name}},
@{n='Parameters';e={$_.ToString()}}
ParameterSetName Parameters
---------------- ----------
Path [-Path] <string[]> [-Lines] [-Words] [-Characters] [-Recurse] [<CommonParameters>]
PathAll [-Path] <string[]> -All [-Recurse] [<CommonParameters>]
LiteralPath -LiteralPath <string[]> [-Lines] [-Words] [-Characters] [<CommonParameters>]
LiteralPathAll -LiteralPath <string[]> -All [<CommonParameters>]
Ensembles de paramètres en action
L’exemple utilise le jeu de PathAll paramètres.
Measure-Lines test* -All
File Lines Words Characters
---- ----- ----- ----------
C:\temp\test\test.help.txt 31 562 2059
C:\temp\test\test.md 30 1527 3224
C:\temp\test\test.ps1 3 3 79
C:\temp\test\test[1].txt 31 562 2059
Erreur lors de l’utilisation des paramètres de plusieurs jeux
Dans cet exemple, des paramètres uniques de différents jeux de paramètres sont utilisés.
Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME
Get-ChildItem: Parameter set cannot be resolved using the specified named
parameters. One or more parameters issued cannot be used together or an
insufficient number of parameters were provided.
Les paramètres Path et LiteralPath sont uniques à différents ensembles de paramètres de l’applet Get-ChildItem de commande. Lorsque les paramètres sont exécutés ensemble dans la même applet de commande, une erreur est levée. Un seul jeu de paramètres peut être utilisé par appel d’applet de commande à la fois.
Comment savoir quel jeu de paramètres est utilisé
La variable $PSCmdlet automatique fournit la propriété ParameterSetName .
Cette propriété contient le nom du jeu de paramètres utilisé. Vous pouvez utiliser cette propriété dans votre fonction pour déterminer quel jeu de paramètres est utilisé pour sélectionner le comportement spécifique à un jeu de paramètres.
function Get-ParameterSetName {
[CmdletBinding(DefaultParameterSetName = 'Set1')]
param (
[Parameter(ParameterSetName = 'Set1', Position = 0)]
$Var1,
[Parameter(ParameterSetName = 'Set2', Position = 0)]
$Var2,
[Parameter(ParameterSetName = 'Set1', Position = 1)]
[Parameter(ParameterSetName = 'Set2', Position = 1)]
$Var3,
[Parameter(Position = 2)]
$Var4
)
"Using Parameter set named '$($PSCmdlet.ParameterSetName)'"
switch ($PSCmdlet.ParameterSetName) {
'Set1' {
"`$Var1 = $Var1"
"`$Var3 = $Var3"
"`$Var4 = $Var4"
break
}
'Set2' {
"`$Var2 = $Var2"
"`$Var3 = $Var3"
"`$Var4 = $Var4"
break
}
}
}
PS> Get-ParameterSetName 1 2 3
Using Parameter set named 'Set1'
$Var1 = 1
$Var3 = 2
$Var4 = 3
PS> Get-ParameterSetName -Var2 1 2 3
Using Parameter set named 'Set2'
$Var2 = 1
$Var3 = 2
$Var4 = 3
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour