THEMA

about_Functions_Advanced_Parameters
KURZBESCHREIBUNG
Erlutert, wie Funktionen, die das CmdletBinding-Attribut
deklarieren, statische und dynamische Parameter hinzugefgt
werden.
DETAILBESCHREIBUNG
Sie knnen beim Schreiben von Funktionen eigene Parameter
deklarieren, und Sie Funktionen schreiben, damit sie auf die
allgemeinen Parameter zugreifen knnen, die fr kompilierte Cmdlets
verfgbar 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
knnen auch jedoch das Alias-Attribut und mehrere Validierungsargu-
mente deklarieren. Die Anzahl der Attribute, die Sie einer
Parameterdeklaration hinzufgen knnen, ist nicht beschrnkt.
Parameter-Attribut
Mit dem Parameter-Attribut knnen Sie einen Parameter der
Funktion deklarieren.
Dieses Attribut verfgt 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
Ausfhren 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 Ausfhren 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 Ausfhren des Cmdlet als
erstes Argument angegeben werden muss. Diese Funktion kann
mit oder ohne Angabe des Parameternamens ausgefhrt werden.
Param
(
[parameter(Position=0)]
[String[]]
$ComputerName
)
Benanntes ParameterSetName-Argument
Das ParameterSetName-Argument gibt den Parametersatz an, zu
dem ein Parameter gehrt. Wenn kein Parametersatz angegeben
wird, gehrt der Parameter zu allen von der Funktion definierten
Parameterstzen. 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 Parameterstzen
gehren.
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Computer")]
[String[]]
$ComputerName
)
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Benutzer")]
[String[]]
$UserName
)
Weitere Informationen zu Parameterstzen finden Sie in der
MSDN Library im Thema "Cmdlet Parameters" unter
"http://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 vollstndige
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 verfgt 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 enthlt. 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 fr den Parameter
an. Die Anzahl der Aliase, die einem Parameter zugewiesen
werden knnen, ist nicht beschrnkt. Im folgenden Beispiel wird
eine erforderliche Parameterdeklaration gezeigt, die dem
ComputerName-Parameter den Alias "CN" hinzufgt.
Param
(
[parameter(Mandatory=$true)]
[alias("CN")]
[String[]]
$ComputerName
)
Parameter-Validierungsattribute
Diese Attribute definieren, wie die Windows PowerShell-Laufzeit
die Argumente erweiterter Funktionen berprft.
AllowNull-Validierungsattribut
Das AllowNull-Attribut ermglicht 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
zulssig. 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
zulssig.
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
knnen. Wenn die Anzahl der Argumente auerhalb dieses
Bereichs liegt, generiert die Windows PowerShell-Laufzeit
einen Fehler. Im folgenden Beispiel kann der ComputerName-Para-
meter ber bis zu fnf Argumente verfgen.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateCount(1,5)]
$ComputerName
)
ValidateLength-Validierungsattribut
Das ValidateLength-Attribut gibt die minimale und die
maximale Lnge des Parameterarguments an. Wenn die Lnge des
Parameterarguments auerhalb dieses Bereichs liegt, generiert
die Windows PowerShell-Laufzeit einen Fehler.
Im folgenden Beispiel mssen 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 regulren Ausdruck
an, mit dem das Muster des Parameterarguments berprft 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 auerhalb dieses Bereichs liegt, generiert
die Windows PowerShell-Laufzeit einen Fehler. Im folgenden
Beispiel darf das Argument des Parameters nicht kleiner als 0
oder grer als 10 sein.
Param
(
[parameter(Mandatory=$true)]
[Int[]]
[ValidateRange(0,10)]
$Count
)
ValidateScript-Validierungsattribut
Das ValidateScript-Attribut gibt ein Skript an, das zum
berprfen des Parameterarguments verwendet wird. Wenn das
Skriptergebnis den Wert "False" besitzt oder das Skript eine
Ausnahme auslst, 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 gltiger Werte fr
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 verfgbar sind.

Beispielsweise verfgen mehrere Anbieter-Cmdlets ber Parame-
ter, die nur verfgbar sind, wenn das Cmdlet im Anbieterpfad
verwendet wird. Ein vertrauter dynamischer Parameter ist der
Encoding-Parameter des Cmdlet "Set-Item", der nur verfgbar
ist, wenn das Cmdlet "Set-Item" in einem FileSystem-
Anbieterpfad verwendet wird.

Verwenden Sie zum Erstellen eines dynamischen Parameters fr
eine Funktion oder ein Skript das DynamicParam-Schlsselwort
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 verfgbar ist.
Erstellen Sie mit dem Cmdlet "New-Object" ein
System.Management.Automation.RuntimeDefinedParameter-Objekt,
um den Parameter darzustellen und seinen Namen anzugeben.
Sie knnen 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 enthlt 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 verfgbar, wenn
der Wert des Path-Parameters "HKLM:" enthlt, 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", [Int
32], $attributeCollection)

$attributes = new-object System.Management.Automation.ParameterAtt
ribute
$attributes.ParameterSetName = 'pset1'
$attributes.Mandatory = $false

$attributeCollection = new-object -Type System.Collections.ObjectM
odel.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
"http://go.microsoft.com/fwlink/?LinkID=145130."


SIEHE AUCH
about_Advanced-Funktionen
about_Functions_Advanced_Methods
about_Functions_CmdletBindingAttribute