about_Parameters

Letzte Aktualisierung: Mai 2014

Betrifft: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

THEMA

about_Parameters

KURZE BESCHREIBUNG

Beschreibt das Arbeiten mit Befehlsparametern in Windows PowerShell.

LANGE BESCHREIBUNG

Die meisten Windows PowerShell-Befehle, z. B. Cmdlets, Funktionen und Skripts, benötigen Parameter, um Benutzern die Auswahl von Optionen oder Bereitstellung von Eingaben zu ermöglichen. Die Parameter folgen dem Befehlsnamen und weisen folgendes Format auf:

        -<parameter_name> <parameter_value>

Dem Parameternamen ist ein Bindestrich (-) vorangestellt, der Windows PowerShell anzeigt, dass das Wort nach dem Bindestrich ein Parametername ist. Einige Parameter benötigen oder akzeptieren keinen Parameterwert. Andere Parameter benötigen einen Wert, der Parametername ist im Befehl jedoch nicht erforderlich.

Es gibt verschiedene Arten von Parametern, und die Anforderungen für diese Parameter variieren. Um Informationen zu den Parametern eines Befehls zu erhalten, verwenden Sie das Cmdlet „Get-Help“. Geben Sie z. B. Folgendes ein, um Informationen zu den Parametern des Cmdlets „Get-ChildItem“ zu erhalten:

        Get-Help Get-ChildItem

Um Informationen zu den Parametern eines Skripts zu suchen, verwenden Sie den vollständigen Pfad zur Skriptdatei. Zum Beispiel:

        Get-Help $home\Documents\Scripts\Get-Function.ps1

Das Get-Help-Cmdlet gibt verschiedene Informationen zum Befehl zurück, z. B. eine Beschreibung, die Befehlssyntax, Informationen zu den Parametern sowie Beispiele zur Verwendung der Parameter in einem Befehl.

Sie können auch den Parameter „Parameter“ des Get-Help-Cmdlets verwenden, um Informationen zu einem bestimmten Parameter zu erhalten. Oder Sie verwenden den Parameter „Parameter“ mit dem Platzhalterzeichen (*), um Informationen zu allen Parametern des Befehls zu erhalten. Der folgende Befehl beispielsweise ruft Informationen zu allen Parametern des Get-Member-Cmdlets ab:

        Get-Help Get-Member -Parameter *

STANDARDWERTE FÜR PARAMETER

Optionale Parameter weisen einen Standardwert auf, der verwendet oder angenommen wird, wenn der Parameter im Befehl nicht angegeben wird.

Ein Beispiel: Der Standardwert für den ComputerName-Parameter vieler Cmdlets ist der Name des lokalen Computers. Demzufolge wird der Name des lokalen Computers im Befehl verwendet, wenn der ComputerName-Parameter nicht angegeben ist.

Den Standardparamaterwert finden Sie im Hilfethema für das Cmdlet. Die Parameterbeschreibung sollte den Standardwert enthalten.

Sie können auch einen benutzerdefinierten Standardwert für einen Parameter eines Cmdlets oder einer erweiterten Funktion festlegen. Informationen zum Festlegen von benutzerdefinierten Standardwerten finden Sie unter „about_Parameters_Default_Values“.

PARAMETERATTRIBUTTABELLE

Wenn Sie die Parameter „Full“, „Parameter“ oder „Online“ des Get-Help-Cmdlets verwenden, zeigt Get-Help eine Parameterattributtabelle mit ausführlichen Informationen zum Parameter an.

Diese Informationen umfassen Details, die Sie zur Verwendung des Parameters benötigen. Das Hilfethema für das Cmdlet „Get-ChildItem“ bietet z. B. die folgenden Informationen zum Path-Parameter:

        -path <string[]>
            Specifies a path of one or more locations. Wildcard characters are
            permitted. The default location is the current directory (.).

        Required?                    false
        Position?                    1
        Default value                Current directory
        Accept pipeline input?       true (ByValue, ByPropertyName)
        Accept wildcard characters?  true

Zu den Parameterinformationen gehören die Parametersyntax, eine Beschreibung des Parameters und die Parameterattribute. In den folgenden Abschnitten werden die Parameterattribute beschrieben.

PARAMETER ERFORDERLICH?

Diese Einstellung gibt an, ob der Parameter obligatorisch ist, d. h., ob alle Befehle, die dieses Cmdlet verwenden, diesen Parameter enthalten müssen. Wenn der Wert „true“ lautet und der Parameter im Befehl fehlt, werden Sie von Windows PowerShell aufgefordert, einen Wert für den Parameter bereitzustellen.

PARAMETERPOSITION?

Diese Einstellung legt fest, ob Sie einen Parameterwert angeben können, ohne diesem den Parameternamen voranzustellen. Wenn die Einstellung „0“ oder „named“ lautet, ist der Parametername erforderlich. Dieser Parametertyp wird als benannter Parameter bezeichnet. Ein benannter Parameter kann an einer beliebigen Position nach dem Namen des Cmdlets aufgeführt werden.

Wenn die Einstellung „Parameterposition?“ auf eine ganze Zahl ungleich 0 festgelegt ist, ist der Name des Parameters nicht erforderlich. Dieser Parametertyp wird als Positionsparameter bezeichnet, und die Zahl gibt die Position an, an der sich der Parameter im Verhältnis zu anderen Positionsparametern befinden muss. Wenn Sie den Parameternamen eines Positionsparameters einschließen, kann der Parameter an einer beliebigen Position nach dem Namen des Cmdlets aufgeführt werden.

Das Cmdlet „Get-ChildItem“ weist beispielsweise die Parameter „Path“ und „Exclude“ auf. Die Einstellung „Parameterposition?“ für „Path“ lautet „1“, es handelt sich also um einen Positionsparameter. Die Einstellung „Parameterposition?“ für „Exclude“ lautet „0“, es handelt sich also um einen benannten Parameter.

Das bedeutet, dass für „Path“ der Name des Parameters nicht erforderlich ist, aber der Parameterwert muss der erste oder einzige Wert eines unbenannten Parameters im Befehl sein. Da es sich bei „Exclude“ um einen benannten Parameter handelt, können Sie diesen an einer beliebigen Position im Befehl platzieren.

Aufgrund der „Parameterposition?“-Einstellungen für diese beiden Parameter können Sie einen der folgenden Befehle verwenden:

        Get-ChildItem -path c:\techdocs -exclude *.ppt
        Get-ChildItem c:\techdocs -exclude *.ppt
        Get-ChildItem -exclude *.ppt -path c:\techdocs
        Get-ChildItem -exclude *.ppt c:\techdocs

Würden Sie einen weiteren Positionsparameter einschließen, ohne den Parameternamen anzugeben, müsste dieser Parameter in der Reihenfolge platziert werden, die durch die Einstellung „Parameterposition?“ festgelegt wird.

PARAMETERTYP

Diese Einstellung gibt den Microsoft .NET Framework-Typ des Parameterwerts an. Wenn der Typ z. B. „Int32“ lautet, muss der Wert des Parameters eine ganze Zahl sein. Wenn der Typ „string“ lautet, muss der Wert des Parameters eine Zeichenfolge sein. Wenn die Zeichenfolge Leerzeichen enthält, muss der Wert in Anführungszeichen eingeschlossen werden, oder den Leerzeichen muss das Escapezeichen (`) vorangestellt werden.

STANDARDWERT

Diese Einstellung gibt den Wert an, den der Parameter annimmt, wenn kein anderer Wert angegeben ist. Der Standardwert für den Path-Parameter beispielweise ist häufig das aktuelle Verzeichnis. Erforderliche Parameter besitzen nie einen Standardwert. Für viele optionale Parameter gibt es keinen Standardwert, da der Parameter keine Auswirkung hat, wenn er nicht verwendet wird.

AKZEPTIERT MEHRERE WERTE?

Diese Einstellung gibt an, ob ein Parameter mehrere Werte akzeptiert. Wenn ein Parameter mehrere Werte akzeptiert, können Sie eine durch Trennzeichen getrennte Liste als Parameterwert in den Befehl eingeben. Sie können auch eine durch Trennzeichen getrennte Liste (ein Array) in einer Variablen speichern und diese Variable als Parameterwert angeben.

Der ServiceName-Parameter des Get-Service-Cmdlets beispielsweise akzeptiert mehrere Werte. Die folgenden Befehle sind beide gültig:

        get-service -servicename winrm, netlogon


        $s = "winrm", "netlogon"
        get-service -servicename $s

AKZEPTIERT PIPELINEEINGABEN?

Diese Einstellung gibt an, ob Sie den Pipelineoperator (|) verwenden können, um einen Wert an den Parameter zu senden.

    
    Value                    Description
    -----                    -----------
    False                    Indicates that you cannot pipe a value to the 
                             parameter.


    True (by Value)          Indicates that you can pipe any value to the 
                             parameter, just so the value has the .NET 
                             Framework type specified for the parameter or the
                             value can be converted to the specified .NET 
                             Framework type.


                             When a parameter is "True (by Value)", Windows 
                             PowerShell tries to associate any piped values 
                             with that parameter before it tries other methods
                             to interpret the command.


    True (by Property Name)  Indicates that you can pipe a value to the 
                             parameter, but the .NET Framework type of the 
                             parameter must include a property with the same
                             name as the parameter.
 
                             For example, you can pipe a value to a Name 
                             parameter only when the value has a property 
                             called "Name".

AKZEPTIERT PLATZHALTERZEICHEN?

Diese Einstellung gibt an, ob der Parameterwert Platzhalterzeichen enthalten kann, damit der Wert mit mehr als einem vorhandenen Element im Zielcontainer verglichen werden kann.

ALLGEMEINE PARAMETER

Allgemeine Parameter sind Parameter, die Sie mit jedem Cmdlet verwenden können. Informationen zu allgemeinen Parametern finden Sie unter „about_CommonParameters“.

SIEHE AUCH

about_Command_syntax

about_Comment_Based_Help

about_Functions_Advanced

about_Parameters_Default_Values

about_Pipelines

about_Wildcards