about_Parameter_Sets

Artykuł
06/21/2023

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żywać tylko jednego zestawu parametrów.

Wymagania dotyczące zestawu parametrów

Poniższe 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. Nie ma dwóch parametrów pozycyjnych, które mogą określać tę samą pozycję.
Tylko jeden parametr w zestawie może zadeklarować ValueFromPipeline słowo kluczowe o wartości true. Wiele parametrów może definiować ValueFromPipelineByPropertyName słowo kluczowe z wartością true.

Uwaga

Istnieje limit 32 zestawów parametrów.

Domyślne zestawy parametrów

Po zdefiniowaniu DefaultParameterSetName wielu zestawów parametrów słowo kluczowe atrybutu CmdletBinding określa domyślny zestaw parametrów. Program PowerShell używa domyślnego zestawu parametrów, jeśli nie może określić zestawu parametrów do użycia 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.

Przykład

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

Ścieżka
PathAll
LiterałPath
LiteralPathAll

function Measure-Lines {
    [CmdletBinding(DefaultParameterSetName = 'Path')]
    param (
        [Parameter(Mandatory = $true,
            ParameterSetName = 'Path',
            HelpMessage = 'Enter one or more filenames',
            Position = 0)]
        [Parameter(Mandatory = $true,
            ParameterSetName = 'PathAll',
            Position = 0)]
        [string[]]$Path,

        [Parameter(Mandatory = $true, ParameterSetName = 'LiteralPathAll')]
        [Parameter(Mandatory = $true,
            ParameterSetName = 'LiteralPath',
            HelpMessage = 'Enter a single filename',
            ValueFromPipeline = $true)]
        [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 = $true, ParameterSetName = 'PathAll')]
        [Parameter(Mandatory = $true, 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
        }

        if ($Path) {
            $Files = Get-ChildItem -Path $Path -Recurse:$Recurse
        }
        else {
            $Files = Get-ChildItem -LiteralPath $LiteralPath
        }
    }
    process {
        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 zestawy parametrów PathAll 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 tym przykładzie używamy 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.

Udostępnij za pośrednictwem