Informationen zu Parametersätzen

Artikel
05/09/2024

KURZE BESCHREIBUNG

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

LANGE BESCHREIBUNG

PowerShell verwendet Parametersätze, damit Sie eine einzelne Funktion schreiben können, die verschiedene Aktionen für verschiedene Szenarien ausführen kann. Mithilfe von Parametersätzen können Sie dem Benutzer verschiedene Parameter verfügbar machen. Und, um unterschiedliche Informationen basierend auf den vom Benutzer angegebenen Parametern zurückzugeben.

Parametersatzanforderungen

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

Jeder Parametersatz muss mindestens einen eindeutigen Parameter aufweisen. Legen Sie diesen Parameter nach Möglichkeit als obligatorischen Parameter fest.
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 den ValueFromPipeline Schlüsselwort (keyword) mit dem Wert deklarierentrue. Mehrere Parameter können die ValueFromPipelineByPropertyName Schlüsselwort (keyword) mit dem Wert definierentrue.
Wenn für einen Parameter kein Parametersatz angegeben wird, gehört der Parameter zu allen Parametersätzen.

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 zu verwendende Parametersatz basierend auf den für den Befehl bereitgestellten Informationen 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 die 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 unterschiedlich definieren. Beispielsweise können Sie einen Parameter in einem Satz als obligatorisch und in einem anderen als optional definieren. Jeder Parametersatz muss jedoch mindestens einen eindeutigen Parameter enthalten.

Parameter, denen kein Parametersatzname zugewiesen ist, gehören zu allen Parametersätzen.

Beispiel

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 = $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
        }
    }
}

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

Use Get-Command -Syntax zeigt die Syntax der einzelnen Parametersätze an. 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

In diesem Beispiel verwenden wir den PathAll Parametersatz.

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

Freigeben über