about_Parameter_Sets

Article
04/01/2024

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 le ValueFromPipeline mot clé avec une valeur de true. Plusieurs paramètres peuvent définir le ValueFromPipelineByPropertyName mot clé avec une valeur de true.

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, le DefaultParameterSetName mot clé 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 le ParameterSetName mot clé 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 can't be resolved using the specified named parameters.
At line:1 char:1
+ Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Get-ChildItem], ParameterBindingException
    + FullyQualifiedErrorId : AmbiguousParameterSet,Microsoft.PowerShell.Commands.GetChildItemCommand

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

Partager via