about_Parameter_Sets

Brève description

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.

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.

Nom du jeu de paramètres réservés

PowerShell réserve le nom __AllParameterSets du jeu de paramètres pour la gestion spéciale.

__AllParameterSets est le nom du paramètre par défaut défini lorsqu’un nom par défaut explicite n’est pas utilisé.

ParameterSetName La définition de l’attribut Paramètre sur __AllParameterSets est équivalente à l’affectation d’un ParameterSetName. Dans les deux cas, le paramètre appartient à tous les jeux de paramètres.

Examples

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 renvoyer 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 LiteralPath les LiteralPathAll jeux de paramètres. Même si les ensembles de paramètres et les PathAll ensembles de paramètres ont tous deux le LiteralPathAll, les paramètres Path et LiteralPath les différencient.

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