about_Parameter_Sets

  • Artikel

Kurze Beschreibung

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 für einen Parameter kein Parametersatz angegeben wird, 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 positionelle Parameter enthält, muss eindeutige Positionen für jeden Parameter definieren. Es ist nicht möglich, dass zwei positionelle Parameter dieselbe Position angeben.

  • Nur ein Parameter in einem Satz kann die ValueFromPipeline Schlüsselwort (keyword) mit einem Wert von truedeklarieren. Mehrere Parameter können die ValueFromPipelineByPropertyName Schlüsselwort (keyword) mit einem Wert von true.

Hinweis

Es gibt einen Grenzwert von 32 Parametersätzen.

Standardparametersätze

Wenn mehrere Parametersätze definiert sind, gibt der DefaultParameterSetName Schlüsselwort (keyword) des CmdletBinding-Attributs 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 CmdletBinding-Attribut finden Sie unter about_Functions_CmdletBindingAttribute.

Deklarieren von Parametersätzen

Um einen Parametersatz zu erstellen, müssen Sie den ParameterSetName Schlüsselwort (keyword) des Parameter-Attributs für jeden Parameter im Parametersatz angeben. Fügen Sie für Parameter, die zu mehreren Parametersätzen gehören, ein Parameter-Attribut für jeden Parametersatz hinzu.

Mit dem Parameter-Attribut 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.

Beispiele

Die folgende Beispielfunktion zählt die Zahlenzeilen, Zeichen und Wörter in einer Textdatei. Mithilfe von Parametern können Sie angeben, welche Werte zurückgegeben werden sollen und welche Dateien Sie messen möchten. 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 Und PathAll Parametersätze Path sind sehr ähnlich, aber der Parametersatz "All" ist für den PathAll Parametersatz eindeutig. Das gleiche gilt für die LiteralPath Und-Parameter-Sätze LiteralPathAll . Obwohl die PathAll Parameter und LiteralPathAll Parameter beide über den Parameter "All " verfügen, unterscheiden sich die Parameter "Path " und "LiteralPath ".

Hier Get-Command -Syntax sehen Sie 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 PathAll Parametersatz 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 verschiedene Parametersätze des Get-ChildItem Cmdlets 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 ParameterSetName-Eigenschaft 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