about_Parameter_Sets

Článek
04/01/2024

Krátký popis

Popisuje, jak definovat a používat sady parametrů v pokročilých funkcích.

Dlouhý popis

PowerShell používá sady parametrů, které umožňují napsat jednu funkci, která může provádět různé akce pro různé scénáře. Sady parametrů umožňují uživateli zpřístupnit různé parametry. A pokud chcete vrátit různé informace na základě parametrů určených uživatelem. Najednou můžete použít pouze jednu sadu parametrů.

Požadavky na sadu parametrů

Následující požadavky platí pro všechny sady parametrů.

Pokud pro parametr není zadána žádná sada parametrů, patří parametr do všech sad parametrů.
Každá sada parametrů musí mít jedinečnou kombinaci parametrů. Pokud je to možné, měl by být alespoň jeden z jedinečných parametrů povinným parametrem.
Sada parametrů, která obsahuje více pozičních parametrů, musí definovat jedinečné pozice pro každý parametr. Žádné dva poziční parametry nemohou určit stejnou pozici.
Pouze jeden parametr v sadě může deklarovat ValueFromPipeline klíčové slovo s hodnotou true. Více parametrů může definovat ValueFromPipelineByPropertyName klíčové slovo s hodnotou true.

Poznámka:

Existuje limit 32 sad parametrů.

Výchozí sady parametrů

Pokud je definováno více sad parametrů, DefaultParameterSetName klíčové slovo atributu CmdletBinding určuje výchozí sadu parametrů. PowerShell používá výchozí sadu parametrů, když nemůže určit sadu parametrů, která se má použít na základě informací zadaných příkazu. Další informace o atributu CmdletBinding najdete v tématu about_Functions_CmdletBindingAttribute.

Deklarace sad parametrů

Chcete-li vytvořit sadu parametrů, je nutné zadat ParameterSetName klíčové slovo atributu Parametr pro každý parametr v sadě parametrů. Pro parametry, které patří do více sad parametrů, přidejte atribut Parameter pro každou sadu parametrů.

Atribut Parameter umožňuje definovat parametr odlišně pro každou sadu parametrů. Parametr můžete například definovat jako povinný v jedné sadě a volitelně v jiné sadě. Každá sada parametrů však musí obsahovat alespoň jeden jedinečný parametr.

Parametry, které nemají přiřazený název sady parametrů, patří do všech sad parametrů.

Příklady

Následující ukázková funkce spočítá číselné řádky, znaky a slova v textovém souboru. Pomocí parametrů můžete určit, které hodnoty chcete vrátit a které soubory chcete měřit. Jsou definovány čtyři sady parametrů:

Cesta
PathAll
LiterálPath
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
        }
    }
}

Každá sada parametrů musí mít jedinečný parametr nebo jedinečnou kombinaci parametrů. PathAll Sady Path parametrů jsou velmi podobné, ale parametr All je jedinečný pro PathAll sadu parametrů. Totéž platí u LiteralPath sad parametrů a LiteralPathAll parametrů. I když obě PathAll sady parametrů LiteralPathAll mají parametr All , parametry Path a LiteralPath je odlišují.

Použití Get-Command -Syntax ukazuje syntaxi každé sady parametrů. Nezobrazuje se ale název sady parametrů. Následující příklad ukazuje, které parametry lze použít v každé sadě parametrů.

(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>]

Sady parametrů v akci

V příkladu PathAll se používá sada parametrů.

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

Chyba při používání parametrů z více sad

V tomto příkladu se používají jedinečné parametry z různých sad parametrů.

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.

Parametry Path a LiteralPath jsou jedinečné pro různé sady parametrů rutiny Get-ChildItem . Když se parametry spustí společně ve stejné rutině, vyvolá se chyba. Na volání rutiny lze současně použít pouze jednu sadu parametrů.

Jak zjistit, která sada parametrů se používá

Automatická proměnná $PSCmdlet poskytuje vlastnost ParameterSetName . Tato vlastnost obsahuje název používané sady parametrů. Tuto vlastnost můžete použít ve své funkci k určení, která sada parametrů se používá k výběru chování specifického pro sadu parametrů.

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