about_Parameter_Sets

Kurzbeschreibung

Beschreibt, wie Parametersätze in erweiterten Funktionen definiert und verwendet werden.

Lange Beschreibung

PowerShell verwendet Parametersätze, mit denen Sie eine einzelne Funktion schreiben können, die unterschiedliche Aktionen für verschiedene Szenarien ausführen kann. Parametersätze ermöglichen es Ihnen, dem Benutzer unterschiedliche Parameter verfügbar zu machen. Und um unterschiedliche Informationen basierend auf den vom Benutzer angegebenen Parametern zurückzugeben. Sie können jeweils nur einen Parameter verwenden.

Parametersatzanforderungen

Die folgenden Anforderungen gelten für alle Parametersätze.

• Wenn kein Parametersatz für einen Parameter angegeben ist, gehört der Parameter zu allen Parametersätzen.

• Jeder Parametersatz muss über eine eindeutige Kombination von Parametern verfügen. Wenn möglich, sollte mindestens einer der eindeutigen Parameter ein obligatorischer Parameter sein.

• Ein Parametersatz, der mehrere Positionsparameter enthält, muss eindeutige Positionen für jeden Parameter definieren. Keine zwei Positionsparameter können dieselbe Position angeben.

Standardparametersätze

Wenn mehrere Parametersätze definiert sind, gibt das DefaultParameterSetName Schlüsselwort des attributs CmdletBinding den Standardparametersatz an. PowerShell verwendet den Standardparametersatz, wenn der Parameter, der basierend auf den informationen für den Befehl bereitgestellt wird, nicht bestimmt werden kann. Weitere Informationen zum attribut CmdletBinding finden Sie unter about_Functions_CmdletBindingAttribute.

Deklarieren von Parametersätzen

Zum Erstellen eines Parametersatzes müssen Sie das ParameterSetName Schlüsselwort des attributs Parameter attributs für jeden Parameter im Parametersatz angeben. Fügen Sie für Parameter, die mehreren Parametersätzen angehören, ein Parameter- Attribut für jeden Parametersatz hinzu.

Mit dem attribut Parameter können Sie den Parameter für jeden Parametersatz anders definieren. Sie können z. B. einen Parameter als obligatorisch in einem Satz und optional in einem anderen definieren. Jeder Parametersatz muss jedoch mindestens einen eindeutigen Parameter enthalten.

Parameter, die keinen zugewiesenen Parametersatznamen haben, gehören zu allen Parametersätzen.

Reservierter Parametersatzname

PowerShell reserviert den Parametersatznamen __AllParameterSets für die spezielle Behandlung.

__AllParameterSets ist der Name des Standardparameters, der festgelegt wird, wenn kein expliziter Standardname verwendet wird.

ParameterSetName Das Festlegen des Parameter-Attributs__AllParameterSets entspricht nicht dem Zuweisen eines ParameterSetName. In beiden Fällen gehört der Parameter zu allen Parametersätzen.

Examples

Die folgende Beispielfunktion zählt die Zahlenzeilen, Zeichen und Wörter in einer Textdatei. Mithilfe von Parametern können Sie die zurückgegebenen Werte und die zu messenden Dateien angeben. Es sind vier Parametersätze definiert:

• Pfad
• PathAll
• LiteralPath
• 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
        }
    }
}

Jeder Parametersatz muss über einen eindeutigen Parameter oder eine eindeutige Kombination von Parametern verfügen. Die Path- und PathAll-Parametersätze sind sehr ähnlich, aber der parameter All ist für den PathAll Parametersatz eindeutig. Das gleiche gilt für die LiteralPath- und LiteralPathAll-Parametersätze. Obwohl der parameter PathAll und LiteralPathAll beide den Parameter All aufweisen, unterscheiden sich die Parameter Path und LiteralPath parameter.

Verwenden Sie Get-Command -Syntax zeigt die Syntax der einzelnen Parametersätze. Der Name des Parametersatzes wird jedoch nicht angezeigt. Das folgende Beispiel zeigt, welche Parameter in jedem Parametersatz verwendet werden können.

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

Parametersätze in Aktion

Im Beispiel wird der parametersatz PathAll verwendet.

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

Fehler beim Verwenden von Parametern aus mehreren Sätzen

In diesem Beispiel werden eindeutige Parameter aus verschiedenen Parametersätzen verwendet.

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.

Die parameter Path und LiteralPath sind für unterschiedliche Parametersätze des Cmdlets Get-ChildItem eindeutig. Wenn die Parameter im selben Cmdlet zusammen ausgeführt werden, wird ein Fehler ausgelöst. Pro Cmdlet-Aufruf kann jeweils nur ein Parametersatz verwendet werden.

So wissen Sie, welcher Parametersatz verwendet wird

Die automatische Variable $PSCmdlet stellt die eigenschaft ParameterSetName bereit. Diese Eigenschaft enthält den Namen des verwendeten Parametersatzes. Sie können diese Eigenschaft in Ihrer Funktion verwenden, um zu bestimmen, welcher Parametersatz zum Auswählen von Parametersatz-spezifischem Verhalten verwendet wird.

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