Cmdlet-Parametersätze

PowerShell verwendet Parametersätze, damit Sie ein einzelnes Cmdlet schreiben können, das verschiedene Aktionen für verschiedene Szenarien ausführen kann. Mit Parametersätzen können Sie verschiedene Parameter für den Benutzer verfügbar machen. Und, um unterschiedliche Informationen basierend auf den vom Benutzer angegebenen Parametern zurück zu geben.

Beispiele für Parametersätze

Das PowerShell-Cmdlet gibt beispielsweise unterschiedliche Informationen zurück, je nachdem, ob der Benutzer Get-EventLog den Parameter List oder LogName angibt. Wenn der List-Parameter angegeben wird, gibt das Cmdlet Informationen zu den Protokolldateien selbst zurück, jedoch nicht zu den Ereignisinformationen, die sie enthalten. Wenn der LogName-Parameter angegeben wird, gibt das Cmdlet Informationen zu den Ereignissen in einem bestimmten Ereignisprotokoll zurück. Die Parameter List und LogName identifizieren zwei separate Parametersätze.

Eindeutiger Parameter

Jeder Parametersatz muss über einen eindeutigen Parameter verfügen, den die PowerShell-Runtime verwendet, um den entsprechenden Parametersatz verfügbar zu machen. Wenn möglich, sollte der eindeutige Parameter ein obligatorischer Parameter sein. Wenn ein Parameter obligatorisch ist, muss der Benutzer den Parameter angeben, und die PowerShell-Runtime verwendet diesen Parameter, um den Parametersatz zu identifizieren. Der eindeutige Parameter kann nicht obligatorisch sein, wenn Ihr Cmdlet für die Ausführung ohne Angabe von Parametern konzipiert ist.

Mehrere Parametersätze

In der folgenden Abbildung zeigt die linke Spalte drei gültige Parametersätze. Parameter A ist für den ersten Parametersatz eindeutig, Parameter B ist für den zweiten Parametersatz eindeutig, und Parameter C ist für den dritten Parametersatz eindeutig. In der rechten Spalte haben die Parametersätze keinen eindeutigen Parameter.

Parametersatzanforderungen

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

• Jeder Parametersatz muss mindestens einen eindeutigen Parameter haben. Machen Sie diesen Parameter nach Möglichkeit zu einem obligatorischen Parameter.

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

• Nur ein Parameter in einem Satz kann das Schlüsselwort mit ValueFromPipeline dem Wert deklarieren. true Mehrere Parameter können das Schlüsselwort ValueFromPipelineByPropertyName mit dem Wert true definieren.

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

Hinweis

Für ein Cmdlet oder eine Funktion gilt ein Grenzwert von 32 Parametersätzen.

Standardparametersätze

Wenn mehrere Parametersätze definiert sind, können Sie das Schlüsselwort des Cmdlet-Attributs verwenden, DefaultParameterSetName um den Standardparametersatz anzugeben. PowerShell verwendet den Standardparametersatz, wenn der zu verwendende Parametersatz nicht anhand der vom Befehl bereitgestellten Informationen bestimmt werden kann. Weitere Informationen zum Cmdlet-Attribut finden Sie unter Cmdlet-Attributdeklaration.

Deklarieren von Parametersätzen

Um einen Parametersatz zu erstellen, müssen Sie das Schlüsselwort angeben, wenn Sie das Parameterattribut für jeden Parameter ParameterSetName im Parametersatz deklarieren. Fügen Sie für Parameter, die zu mehreren Parametersätzen gehören, ein Parameterattribut für jeden Parametersatz hinzu. Mit diesem 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 optional definieren. Jeder Parametersatz muss jedoch einen eindeutigen Parameter enthalten. Weitere Informationen finden Sie unter ParameterAttributdeklaration.

Im folgenden Beispiel ist der UserName-Parameter der eindeutige Parameter des Parametersets, und der ComputerName-Parameter ist der eindeutige Parameter Test01 des Test02 Parametersets. Der SharedParam-Parameter gehört zu beiden Sätzen und ist für den Test01 Parametersatz obligatorisch, aber für den Test02 Parametersatz optional.

[Parameter(Position = 0, Mandatory = true, ParameterSetName = "Test01")]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

[Parameter(Position = 0, Mandatory = true, ParameterSetName = "Test02")]
public string ComputerName
{
  get { return computerName; }
  set { computerName = value; }
}
private string computerName;

[Parameter(Mandatory= true, ParameterSetName = "Test01")]
[Parameter(ParameterSetName = "Test02")]
public string SharedParam
{
    get { return sharedParam; }
    set { sharedParam = value; }
}
private string sharedParam;