about_Parameter_Sets

Krótki opis

Opisuje sposób definiowania i używania zestawów parametrów w funkcjach zaawansowanych.

Długi opis

Program PowerShell używa zestawów parametrów, aby umożliwić pisanie pojedynczej funkcji, która może wykonywać różne akcje w różnych scenariuszach. Zestawy parametrów umożliwiają uwidocznienie różnych parametrów użytkownikowi. Aby zwrócić różne informacje na podstawie parametrów określonych przez użytkownika. Jednocześnie można użyć tylko jednego zestawu parametrów.

Wymagania dotyczące zestawu parametrów

Następujące wymagania dotyczą wszystkich zestawów parametrów.

• Jeśli dla parametru nie określono żadnego zestawu parametrów, parametr należy do wszystkich zestawów parametrów.

• Każdy zestaw parametrów musi mieć unikatową kombinację parametrów. Jeśli to możliwe, co najmniej jeden z unikatowych parametrów powinien być obowiązkowym parametrem.

• Zestaw parametrów zawierający wiele parametrów pozycyjnych musi definiować unikatowe pozycje dla każdego parametru. Żadne dwa parametry pozycyjne nie mogą określać tej samej pozycji.

Domyślne zestawy parametrów

Gdy zdefiniowano wiele zestawów parametrów, słowo DefaultParameterSetName kluczowe atrybutu CmdletBinding określa domyślny zestaw parametrów. Program PowerShell używa domyślnego zestawu parametrów, gdy nie może określić, który parametr ma być używany na podstawie informacji dostarczonych do polecenia. Aby uzyskać więcej informacji na temat atrybutu CmdletBinding, zobacz about_Functions_CmdletBindingAttribute.

Deklarowanie zestawów parametrów

Aby utworzyć zestaw parametrów, należy określić ParameterSetName słowo kluczowe atrybutu Parametr dla każdego parametru w zestawie parametrów. W przypadku parametrów należących do wielu zestawów parametrów dodaj atrybut Parametr dla każdego zestawu parametrów.

Atrybut Parametr umożliwia definiowanie parametru inaczej dla każdego zestawu parametrów. Można na przykład zdefiniować parametr jako obowiązkowy w jednym zestawie i opcjonalnie w innym. Jednak każdy zestaw parametrów musi zawierać co najmniej jeden unikatowy parametr.

Parametry, które nie mają przypisanej nazwy zestawu parametrów, należą do wszystkich zestawów parametrów.

Nazwa zestawu parametrów zarezerwowanych

Program PowerShell rezerwuje nazwę __AllParameterSets zestawu parametrów na potrzeby specjalnej obsługi.

__AllParameterSets to nazwa domyślnego zestawu parametrów, gdy nie jest używana jawna nazwa domyślna.

ParameterSetName Ustawienie atrybutu Parametr na __AllParameterSets jest równoważne, aby nie przypisywać ParameterSetNameelementu . W obu przypadkach parametr należy do wszystkich zestawów parametrów.

Przykłady

Poniższa przykładowa funkcja zlicza wiersze liczbowe, znaki i wyrazy w pliku tekstowym. Za pomocą parametrów można określić wartości, które mają zostać zwrócone, oraz pliki, które chcesz zmierzyć. Zdefiniowano cztery zestawy parametrów:

• Ścieżka
• PathAll
• LiterałPath
• LiterałPathAll

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żdy zestaw parametrów musi mieć unikatowy parametr lub unikatową kombinację parametrów. Path Zestawy parametrów i PathAll są bardzo podobne, ale parametr All jest unikatowy dla zestawu parametrówPathAll. To samo dotyczy zestawów parametrów LiteralPath i LiteralPathAll . Mimo że PathAll zestawy parametrów i LiteralPathAll mają parametr All , parametry Path i LiteralPath je rozróżniają.

Użycie Get-Command -Syntax pokazuje składnię każdego zestawu parametrów. Nie wyświetla jednak nazwy zestawu parametrów. W poniższym przykładzie pokazano, które parametry mogą być używane w każdym zestawie parametrów.

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

Zestawy parametrów w akcji

W przykładzie użyto zestawu parametrów PathAll .

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

Błąd podczas używania parametrów z wielu zestawów

W tym przykładzie używane są unikatowe parametry z różnych zestawów parametrów.

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 i LiteralPath są unikatowe dla różnych zestawów parametrów Get-ChildItem polecenia cmdlet. Gdy parametry są uruchamiane razem w tym samym poleceniu cmdlet, zgłaszany jest błąd. Jednocześnie można użyć tylko jednego zestawu parametrów na wywołanie polecenia cmdlet.

Jak dowiedzieć się, który zestaw parametrów jest używany

Zmienna $PSCmdlet automatyczna udostępnia właściwość ParameterSetName . Ta właściwość zawiera nazwę używanego zestawu parametrów. Za pomocą tej właściwości w funkcji można określić, który zestaw parametrów jest używany do wybierania zachowania specyficznego dla zestawu parametrów.

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