Cmdlet-Parametertypen

In diesem Thema werden die verschiedenen Parametertypen beschrieben, die Sie in Cmdlets deklarieren können. Cmdlet-Parameter können positional, benannt, erforderlich, optional oder [switch] Parameter sein.

Positions- und benannte Parameter

Alle Cmdlet-Parameter sind benannte oder Positionsparameter. Ein benannter Parameter erfordert, dass Sie beim Aufrufen des Cmdlets den Parameternamen und das Argument eingeben. Ein Positionsparameter erfordert nur, dass Sie die Argumente in relativer Reihenfolge eingeben. Das System ordnet dann das erste nicht benannte Argument dem ersten Positionsparameter zu. Das System ordnet das zweite nicht benannte Argument dem zweiten unbenannten Parameter usw. zu. Standardmäßig sind alle Cmdlet-Parameter benannte Parameter.

Um einen benannten Parameter zu definieren, lassen Sie das schlüsselwort Position in der Parameter Attributdeklaration aus, wie in der folgenden Parameterdeklaration gezeigt.

[Parameter(ValueFromPipeline=true)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Um einen Positionsparameter zu definieren, fügen Sie das Position Schlüsselwort in der Parameter-Attributdeklaration hinzu, und geben Sie dann eine Position an. Im folgenden Beispiel wird der UserName Parameter als Positionsparameter mit Position 0 deklariert. Dies bedeutet, dass das erste Argument des Aufrufs automatisch an diesen Parameter gebunden ist.

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Hinweis

Ein guter Cmdlet-Entwurf empfiehlt, dass die am häufigsten verwendeten Parameter als Positionsparameter deklariert werden, damit der Benutzer den Parameternamen nicht eingeben muss, wenn das Cmdlet ausgeführt wird.

Positions- und benannte Parameter akzeptieren einzelne Argumente oder mehrere durch Kommas getrennte Argumente. Mehrere Argumente sind nur zulässig, wenn der Parameter eine Auflistung akzeptiert, z. B. ein Array von Zeichenfolgen. Sie können Positions- und benannte Parameter im selben Cmdlet kombinieren. In diesem Fall ruft das System zuerst die benannten Argumente ab und versucht dann, die verbleibenden nicht benannten Argumente den Positionsparametern zuzuordnen.

Die folgenden Befehle zeigen die verschiedenen Möglichkeiten, wie Sie einzelne und mehrere Argumente für die Parameter des Cmdlets Get-Command angeben können. Beachten Sie, dass in den letzten beiden Beispielen -Name nicht angegeben werden muss, da der parameter Name als Positionsparameter definiert ist.

Get-Command -Name Get-Service
Get-Command -Name Get-Service,Set-Service
Get-Command Get-Service
Get-Command Get-Service,Set-Service

Obligatorische und optionale Parameter

Sie können cmdlet-Parameter auch als obligatorische oder optionale Parameter definieren. (Ein obligatorischer Parameter muss angegeben werden, bevor die PowerShell-Laufzeit das Cmdlet aufruft.) Standardmäßig werden Parameter als optional definiert.

Um einen obligatorischen Parameter zu definieren, fügen Sie das Mandatory Schlüsselwort in der Parameter-Attributdeklaration hinzu, und legen Sie ihn auf truefest, wie in der folgenden Parameterdeklaration gezeigt.

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

Um einen optionalen Parameter zu definieren, lassen Sie das schlüsselwort Mandatory in der Parameter Attributdeklaration aus, wie in der folgenden Parameterdeklaration gezeigt.

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

[switch] Parameter

PowerShell stellt einen System.Management.Automation.SwitchParameter Typ bereit, mit dem Sie einen Parameter definieren können, dessen Standardwert false, es sei denn, der Parameter wird beim Aufrufen des Cmdlets angegeben. Verwenden Sie [switch] nach Möglichkeit Parameter anstelle von booleschen Parametern.

Betrachten Sie das folgende Beispiel. Viele PowerShell-Cmdlets geben die Ausgabe zurück. Diese Cmdlets weisen jedoch einen PassThru[switch] Parameter auf, der das Standardverhalten außer Kraft setzt. Wenn Sie den parameter PassThru verwenden, gibt das Cmdlet Ausgabeobjekte an die Pipeline zurück.

Das folgende Beispiel zeigt, wie Sie einen [switch] Parameter definieren:

[Parameter()]
public SwitchParameter GoodBye
{
  get { return goodbye; }
  set { goodbye = value; }
}
private bool goodbye;

Verwenden Sie die folgende Struktur innerhalb einer der Eingabeverarbeitungsmethoden, um das Cmdlet für den Parameter zu verwenden, wenn er angegeben ist.

protected override void ProcessRecord()
{
  WriteObject("Switch parameter test: " + userName + ".");
  if (goodbye)
  {
    WriteObject(" Goodbye!");
  }
} // End ProcessRecord

Standardmäßig [switch] werden Parameter aus Positionsparametern ausgeschlossen. Sie können dies im attribut Parameter außer Kraft setzen, die Benutzer jedoch verwirren.

Entwurfsparameter [switch] , sodass die Verwendung des Parameters das Standardverhalten des Befehls in einen weniger gängigen oder komplizierteren Modus ändert. Das einfachste Verhalten eines Befehls sollte das Standardverhalten sein, das die Verwendung von [switch] Parametern nicht erfordert. Basieren Sie auf dem [switch] Verhalten, das vom Parameter gesteuert wird, auf den Wert des Parameters, nicht auf dessen Anwesenheit.

Es gibt mehrere Möglichkeiten zum Testen des Vorhandenseins eines [switch] Parameters:

• MyInvocation.BoundParameters enthält den [switch] Parameternamen als Schlüssel.
• PSCmdlet.ParameterSetName wenn der [switch] Parameter einen eindeutigen Parametersatz definiert

Beispielsweise ist es möglich, einen expliziten Wert für den Schalter mithilfe von -MySwitch:$false oder Splatting bereitzustellen. Wenn Sie nur testen, ob der Parameter vorhanden ist, verhält sich der Befehl so, als ob der Schalterwert anstelle von $true$false ist.

Siehe auch

Schreiben eines Windows PowerShell-Cmdlets