THEMA about_Functions_Advanced_Parameters KURZBESCHREIBUNG Erläutert, wie Funktionen, die das CmdletBinding-Attribut deklarieren, statische und dynamische Parameter hinzugefügt werden. DETAILBESCHREIBUNG Sie können beim Schreiben von Funktionen eigene Parameter deklarieren, und Sie Funktionen schreiben, damit sie auf die allgemeinen Parameter zugreifen können, die für kompilierte Cmdlets verfügbar sind. Weitere Informationen zu den allgemeinen Parametern von Windows PowerShell finden Sie unter "about_CommonParameters". Statische Parameter Im folgenden Beispiel wird eine Parameterdeklaration veranschaulicht, in der ein ComputerName-Parameter definiert wird. Dieser Parameter besitzt die folgenden Eigenschaften: - Er ist erforderlich. - Er akzeptiert Eingaben von der Pipeline. - Er akzeptiert Zeichenfolgenarrays als Eingabe. Param ( [parameter(Mandatory=$true, ValueFromPipeline=$true)] [String[]] $ComputerName ) Das einzige erforderliche Attribut, das beim Deklarieren eines Parameters verwendet werden muss, ist das Parameter-Attribut. Sie können auch jedoch das Alias-Attribut und mehrere Validierungsargu- mente deklarieren. Die Anzahl der Attribute, die Sie einer Parameterdeklaration hinzufügen können, ist nicht beschränkt. Parameter-Attribut Mit dem Parameter-Attribut können Sie einen Parameter der Funktion deklarieren. Dieses Attribut verfügt über die folgenden benannten Argumente, über die die Eigenschaften des Parameters definiert werden, z. B., ob es sich um einen erforderlichen oder einen optionalen Parameter handelt. Benanntes Mandatory-Argument Das Mandatory-Argument gibt an, dass der Parameter beim Ausführen der Funktion erforderlich ist. Wenn dieses Argument nicht angegeben wird, handelt es sich um einen optionalen Parameter. Das folgende Beispiel zeigt die Deklaration eines Parameters, der beim Ausführen der Funktion erforderlich ist. Param ( [parameter(Mandatory=$true)] [String[]] $ComputerName ) Benanntes Position-Argument Das Position-Argument gibt die Position des Parameters an. Wenn dieses Argument nicht angegeben wird, muss der Parametername oder dessen Alias beim Festlegen des Parameters explizit angegeben werden. Wenn kein Parameter einer Funktion Positionen aufweist, weist die Windows PowerShell-Laufzeit zudem jedem Parameter anhand der Reihenfolge, in der diese empfangen werden, Positionen zu. Im folgenden Beispiel wird die Deklaration eines Parameters veranschaulicht, dessen Wert beim Ausführen des Cmdlet als erstes Argument angegeben werden muss. Diese Funktion kann mit oder ohne Angabe des Parameternamens ausgeführt werden. Param ( [parameter(Position=0)] [String[]] $ComputerName ) Benanntes ParameterSetName-Argument Das ParameterSetName-Argument gibt den Parametersatz an, zu dem ein Parameter gehört. Wenn kein Parametersatz angegeben wird, gehört der Parameter zu allen von der Funktion definierten Parametersätzen. Bei diesem Verhalten muss jeder Parametersatz einen eindeutigen Parameter enthalten, der nicht auch Element eines anderen Parametersatzes ist. Im folgenden Beispiel wird die Parameterdeklarati on zweier Parameter gezeigt, die zu zwei verschiedenen Parametersätzen gehören. Param ( [parameter(Mandatory=$true, ParameterSetName="Computer")] [String[]] $ComputerName ) Param ( [parameter(Mandatory=$true, ParameterSetName="Benutzer")] [String[]] $UserName ) Weitere Informationen zu Parametersätzen finden Sie in der MSDN Library im Thema "Cmdlet Parameters" unter "https://go.microsoft.com/fwlink/?LinkId=142183". Benanntes ValueFromPipeline-Argument Das ValueFromPipeline-Argument gibt an, dass der Parameter Eingaben von einem Pipelineobjekt akzeptiert. Geben Sie dieses Argument an, wenn das Cmdlet auf das vollständige Objekt, nicht nur auf eine Eigenschaft des Objekts zugreift. Im folgenden Beispiel wird die Parameterdeklaration eines erforderlichen ComputerName-Parameters veranschaulicht, der das von der Pipeline an die Funktion übergebene Eingabeobjekt akzeptiert. Param ( [parameter(Mandatory=$true, ValueFromPipeline=$true)] [String[]] $ComputerName ) Benanntes valueFromPipelineByPropertyName-Argument Das valueFromPipelineByPropertyName-Argument gibt an, dass der Parameter Eingaben von einer Eigenschaft eines Pipelineobjekts akzeptiert. Geben Sie dieses Attribut an, wenn die folgenden Bedingungen auf True festgelegt sind: - Der Parameter greift auf eine Eigenschaft des über die Pipeline übergebenen Objekts zu. - Die Eigenschaft besitzt den gleichen Namen wie der Parameter, oder die Eigenschaft verfügt über den gleichen Alias wie der Parameter. Wenn die Funktion z. B. einen ComputerName-Parameter aufweist und das über die Pipeline übergebene Objekt eine ComputerName-Eigenschaft besitzt, wird der Wert der ComputerName-Eigenschaft dem ComputerName-Parameter der Funktion zugewiesen. Im folgenden Beispiel wird die Parameterdeklaration eines ComputerName-Parameters veranschaulicht, der Eingaben von der ComputerName-Eigenschaft des an das Cmdlet übergebenen Eingabeobjekts akzeptiert. Param ( [parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)] [String[]] $ComputerName ) Benanntes ValueFromRemainingArguments-Argument Das ValueFromRemainingArguments-Argument gibt an, dass der Parameter alle verbleibenden, nicht an die Parameter der Funktion gebundenen Argumente akzeptiert. Im folgenden Beispiel wird die Parameterdeklaration eines ComputerName-Para- meters veranschaulicht, der alle verbleibenden Argumente des an die Funktion übergebenen Eingabeobjekts akzeptiert. Param ( [parameter(Mandatory=$true, ValueFromRemainingArguments=$true)] [String[]] $ComputerName ) Benanntes HelpMessage-Argument Das HelpMessage-Argument gibt eine Meldung an, die eine kurze Beschreibung des Parameters enthält. Im folgenden Beispiel wird eine Parameterdeklaration mit einer Beschreibung des Parameters gezeigt. Param ( [parameter(Mandatory=$true, HelpMessage="Ein Array von Computernamen.")] [String[]] $ComputerName ) Alias-Attribut Das Alias-Attribut gibt einen anderen Namen für den Parameter an. Die Anzahl der Aliase, die einem Parameter zugewiesen werden können, ist nicht beschränkt. Im folgenden Beispiel wird eine erforderliche Parameterdeklaration gezeigt, die dem ComputerName-Parameter den Alias "CN" hinzufügt. Param ( [parameter(Mandatory=$true)] [alias("CN")] [String[]] $ComputerName ) Parameter-Validierungsattribute Diese Attribute definieren, wie die Windows PowerShell-Laufzeit die Argumente erweiterter Funktionen überprüft. AllowNull-Validierungsattribut Das AllowNull-Attribut ermöglicht es, das Argument eines erforderlichen Cmdlet-Parameters auf NULL festzulegen. Im folgenden Beispiel kann der ComputerName-Parameter den Wert NULL enthalten, obwohl es sich um einen erforderlichen Parameter handelt. Param ( [parameter(Mandatory=$true)] [String] [AllowNull()] $ComputerName ) AllowEmptyString-Validierungsattribut Bei Verwendung des AllowEmptyString-Attributs ist eine leere Zeichenfolge als Argument eines erforderlichen Cmdlet-Parameters zulässig. Im folgenden Beispiel kann der ComputerName-Parameter eine leere Zeichenfolge ("") enthalten, obwohl es sich um einen erforderlichen Parameter handelt. Param ( [parameter(Mandatory=$true)] [String] [AllowEmptyString()] $ComputerName ) AllowEmptyCollection-Validierungsattribut Bei Verwendung des AllowEmptyCollection-Attributs ist eine leere Auflistung als Argument eines erforderlichen Parameters zulässig. Param ( [parameter(Mandatory=$true)] [String[]] [AllowEmptyCollection()] $ComputerName ) ValidateCount-Validierungsattribut Das ValidateCount-Attribut gibt die minimale und die maximale Anzahl von Argumenten an, die vom Parameter akzeptiert werden können. Wenn die Anzahl der Argumente außerhalb dieses Bereichs liegt, generiert die Windows PowerShell-Laufzeit einen Fehler. Im folgenden Beispiel kann der ComputerName-Para- meter über bis zu fünf Argumente verfügen. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateCount(1,5)] $ComputerName ) ValidateLength-Validierungsattribut Das ValidateLength-Attribut gibt die minimale und die maximale Länge des Parameterarguments an. Wenn die Länge des Parameterarguments außerhalb dieses Bereichs liegt, generiert die Windows PowerShell-Laufzeit einen Fehler. Im folgenden Beispiel müssen die angegebenen Computernamen zwischen ein und zehn Zeichen enthalten. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateLength(1,10)] $ComputerName ) ValidatePattern-Validierungsattribut Das ValidatePattern-Attribut gibt einen regulären Ausdruck an, mit dem das Muster des Parameterarguments überprüft wird. Wenn das Parameterargument nicht mit diesem Muster übereinstimmt, generiert die Windows PowerShell-Laufzeit einen Fehler. Im folgenden Beispiel muss das Argument des Parameters aus einer vierstelligen Zahl bestehen, und jede Ziffer muss eine Zahl zwischen 0 und 9 sein. Param ( [parameter(Mandatory=$true)] [String[]] [ValidatePattern("[0-9][0-9][0-9][0-9]")] $ComputerName ) ValidateRange-Validierungsattribut Das ValidateRange-Attribut gibt den minimalen und den maximalen Wert des Parameterarguments an. Wenn das Parameterargument außerhalb dieses Bereichs liegt, generiert die Windows PowerShell-Laufzeit einen Fehler. Im folgenden Beispiel darf das Argument des Parameters nicht kleiner als 0 oder größer als 10 sein. Param ( [parameter(Mandatory=$true)] [Int[]] [ValidateRange(0,10)] $Count ) ValidateScript-Validierungsattribut Das ValidateScript-Attribut gibt ein Skript an, das zum Überprüfen des Parameterarguments verwendet wird. Wenn das Skriptergebnis den Wert "False" besitzt oder das Skript eine Ausnahme auslöst, generiert die Windows PowerShell-Laufzeit einen Fehler. Im folgenden Beispiel muss der Wert des Count-Parameters kleiner als 4 sein. Param ( [parameter()] [Int] [ValidateScript({$_ -lt 4})] $Count ) ValidateSet-Attribut Das ValidateSet-Attribut gibt einen Satz gültiger Werte für das Argument des Parameters an. Wenn das Parameterargument nicht mit einem Wert im Satz übereinstimmt, generiert die Windows PowerShell-Laufzeit einen Fehler. Im folgenden Beispiel darf das Argument des Parameters nur die Namen Sven, Monica und Christian enthalten. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateRange ("Sven", "Monica", "Christian")] $UserName ) ValidateNotNull-Validierungsattribut Das ValidateNotNull-Attribut gibt an, dass das Argument des Parameters nicht auf NULL festgelegt werden darf. Wenn der Parameterwert NULL ist, generiert die Windows PowerShell-Lauf- zeit einen Fehler. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateNotNull()] $UserName ) ValidateNotNullOrEmpty-Validierungsattribut Das ValidateNotNullOrEmpty-Attribut gibt an, dass das Argument des Parameters nicht auf NULL festgelegt und nicht leer sein darf. Wenn der Parameter angegeben wurde, sein Wert jedoch NULL, eine leere Zeichenfolge oder ein leeres Array ist, generiert die Windows PowerShell-Laufzeit einen Fehler. Param ( [parameter(Mandatory=$true)] [String[]] [ValidateNotNullOrEmpty()] $UserName ) Dynamische Parameter Dynamische Parameter sind Parameter eines Cmdlet, einer Funktion oder eines Skripts, die nur unter bestimmten Bedin- gungen verfügbar sind. Beispielsweise verfügen mehrere Anbieter-Cmdlets über Parame- ter, die nur verfügbar sind, wenn das Cmdlet im Anbieterpfad verwendet wird. Ein vertrauter dynamischer Parameter ist der Encoding-Parameter des Cmdlet "Set-Item", der nur verfügbar ist, wenn das Cmdlet "Set-Item" in einem FileSystem- Anbieterpfad verwendet wird. Verwenden Sie zum Erstellen eines dynamischen Parameters für eine Funktion oder ein Skript das DynamicParam-Schlüsselwort Die Syntax lautet wie folgt. DynamicParam {<statement-list>} Verwenden Sie in der Anweisungsliste eine If-Anweisung, um die Bedingungen anzugeben, unter denen der Parameter in der Funktion verfügbar ist. Erstellen Sie mit dem Cmdlet "New-Object" ein System.Management.Automation.RuntimeDefinedParameter-Objekt, um den Parameter darzustellen und seinen Namen anzugeben. Sie können auch mit dem Befehl "New-Object" ein System.Management.Automation.ParameterAttribute-Objekt erstellen, um Attribute des Parameters, z. B. Mandatory, Position oder ValueFromPipeline, oder seinen Parametersatz darzustellen Das folgende Beispiel enthält eine Funktion mit den Standard- parametern "Name" und "Path" sowie einen optionalen dynami- schen Parameter mit dem Namen "DP1". Der DP1-Parameter stammt aus dem PSet1-Parametersatz, und er ist vom "TypInt32". Der DP1-Parameter ist in der Beispielfunktion nur verfügbar, wenn der Wert des Path-Parameters "HKLM:" enthält, um anzugeben, dass er auf dem Registrierungslaufwerk "HKEY_LOCAL_MACHINE" verwendet wird. function Sample { Param ([String]$Name, [String]$Path) DynamicParam { if ($path -match "*HKLM*:") { $dynParam1 = new-object System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection) $attributes = new-object System.Management.Automation.ParameterAttribute $attributes.ParameterSetName = 'pset1' $attributes.Mandatory = $false $attributeCollection = new-object -Type System.Collections.ObjectModel.Collection``1[System.Attribute] $attributeCollection.Add($attributes) $paramDictionary = new-object System.Management.Automation.RuntimeDefinedParameterDictionary $paramDictionary.Add("dp1", $dynParam1) return $paramDictionary } End if } } Weitere Informationen finden Sie unter "RuntimeDefinedParameter Class" in der MSDN (Microsoft Developer Network) Library unter "https://go.microsoft.com/fwlink/?LinkID=145130." SIEHE AUCH about_Advanced-Funktionen about_Functions_Advanced_Methods about_Functions_CmdletBindingAttribute