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




Inhaltsverzeichnis