about_Parameters
Kurze Beschreibung
Beschreibt das Arbeiten mit Befehlsparametern in PowerShell.
Lange Beschreibung
Die meisten PowerShell-Befehle, z. B. Cmdlets, Funktionen und Skripts, basieren auf Parametern, damit Benutzer Optionen auswählen oder Eingaben bereitstellen können. Die Parameter folgen dem Befehlsnamen und haben die folgende Form:
-<parameter_name> <parameter_value>
-<parameter_name>:<parameter_value>
Dem Namen des Parameters wird ein Bindestrich () vorangestellt,- der PowerShell signalisiert, dass das Wort nach dem Bindestrich ein Parametername ist. Der Parametername und -wert können durch ein Leerzeichen oder ein Doppelpunktzeichen getrennt werden. Einige Parameter erfordern oder akzeptieren keinen Parameterwert. Andere Parameter erfordern einen Wert, aber nicht den Parameternamen im Befehl.
Der Typ der Parameter und die Anforderungen für diese Parameter variieren. Um Informationen zu den Parametern eines Befehls zu finden, verwenden Sie das Get-Help Cmdlet. Geben Sie beispielsweise Folgendes ein, um Informationen zu den Parametern des Get-ChildItem Cmdlets zu suchen:
Get-Help Get-ChildItem
Um Informationen zu den Parametern eines Skripts zu finden, verwenden Sie den vollständigen Pfad zur Skriptdatei. Beispiel:
Get-Help $HOME\Documents\Scripts\Get-Function.ps1
Das Get-Help Cmdlet gibt verschiedene Details zum Befehl zurück, einschließlich einer Beschreibung, der Befehlssyntax, Informationen zu den Parametern und Beispielen zur Verwendung der Parameter in einem Befehl.
Sie können auch den Parameter Get-Help des Cmdlets verwenden, um Informationen zu einem bestimmten Parameter zu finden. Alternativ können Sie den Parameterparameter mit dem Wert des Feldhalterzeichens ( * ) verwenden, um Informationen zu allen Parametern des Befehls zu finden. Der folgende Befehl ruft beispielsweise Informationen zu allen Parametern des Get-Member Cmdlets ab:
Get-Help Get-Member -Parameter *
Standardwerte für Parameter
Optionale Parameter verfügen über einen Standardwert, d. h. den Wert, der verwendet oder angenommen wird, wenn der Parameter im Befehl nicht angegeben wird.
Der Standardwert des ComputerName-Parameters vieler Cmdlets ist beispielsweise der Name des lokalen Computers. Daher wird der lokale Computername im Befehl verwendet, es sei denn, der ComputerName-Parameter wird angegeben.
Informationen zum Ermitteln des Standardwerts finden Sie im Hilfethema für das Cmdlet. Die Parameterbeschreibung sollte den Standardwert enthalten.
Sie können auch einen benutzerdefinierten Standardwert für jeden Parameter eines Cmdlets oder einer erweiterten Funktion festlegen. Informationen zum Festlegen benutzerdefinierter Standardwerte finden Sie unter about_Parameters_Default_Values.
Parameterattributetabelle
Wenn Sie die Parameter Full, Parameter oder Online des Get-Help Cmdlets verwenden, Get-Help wird eine Parameterattributetabelle mit ausführlichen Informationen zum Parameter angezeigt.
Diese Informationen enthalten die Details, die Sie für die Verwendung des Parameters wissen müssen.
Das Hilfethema für das Get-ChildItem Cmdlet enthält beispielsweise die folgenden Details 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? 0
Default value Current directory
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? true
Die Parameterinformationen umfassen 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 ist und der Parameter im Befehl fehlt, werden Sie von PowerShell zur Eingabe eines Werts für den Parameter aufgefordert.
Parameterposition
Wenn die Position Einstellung auf eine nicht negative ganze Zahl festgelegt ist, ist der Parametername nicht erforderlich. Dieser Parametertyp wird als Positionsparameter bezeichnet, und die Zahl gibt die Position an, an der der Parameter im Verhältnis zu anderen Positionsparametern angezeigt werden muss. Ein benannter Parameter kann an einer beliebigen Position nach dem Cmdletnamen aufgeführt werden. Wenn Sie den Parameternamen für einen Positionsparameter einschließen, kann der Parameter an einer beliebigen Position nach dem Cmdletnamen aufgeführt werden.
Das Cmdlet verfügt beispielsweise über die Get-ChildItem Parameter Path und Exclude. Die Position Einstellung für Pfad ist 0, was bedeutet, dass es sich um einen Positionsparameter handelt. Die Position Einstellung für Exclude ist benannt.
Dies bedeutet, dass Path nicht den Parameternamen erfordert, sondern sein Parameterwert der erste oder nur unbenannte Parameterwert im Befehl sein muss. Da der Exclude-Parameter jedoch ein benannter Parameter ist, können Sie ihn an einer beliebigen Position im Befehl platzieren.
Aufgrund der Position 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
Wenn Sie einen anderen Positionsparameter ohne Den Parameternamen einschließen würden, muss dieser Parameter in der von der Position Einstellung angegebenen Reihenfolge platziert werden.
Parametertyp
Diese Einstellung gibt den Microsoft .NET Framework Typ des Parameterwerts an. Wenn der Typ beispielsweise Int32 ist, muss der Parameterwert eine ganze Zahl sein. Wenn der Typ Zeichenfolge ist, muss der Parameterwert 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 wird. Der Standardwert des Path-Parameters ist z. B. häufig das aktuelle Verzeichnis. Erforderliche Parameter verfügen nie über einen Standardwert. Für viele optionale Parameter gibt es keinen Standardwert, da der Parameter keine Auswirkungen hat, wenn er nicht verwendet wird.
Akzeptiert mehrere Werte
Diese Einstellung gibt an, ob ein Parameter mehrere Parameterwerte akzeptiert. Wenn ein Parameter mehrere Werte akzeptiert, können Sie eine durch Trennzeichen getrennte Liste als Wert des Parameters im Befehl eingeben oder eine durch Trennzeichen getrennte Liste (ein Array) in einer Variablen speichern und dann die Variable als Parameterwert angeben.
Der Name-Parameter des Get-Service Cmdlets akzeptiert beispielsweise mehrere Werte. Die folgenden Befehle sind gültig:
Get-Service -Name winrm, netlogon
$s = "winrm", "netlogon"
Get-Service -Name $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.
Wenn ein Parameter "True (nach Wert)" ist, versucht PowerShell, diesem Parameter alle pipedierten Werte zuzuordnen, bevor es andere Methoden zum Interpretieren des Befehls versucht.
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.
Beispielsweise können Sie einen Wert nur dann an einen Name-Parameter übergeben, wenn der Wert über eine Eigenschaft namens Name verfügt.
Hinweis
Ein typisierter Parameter, der die Pipelineeingabe (by Value) oder (by PropertyName) akzeptiert, ermöglicht die Verwendung von Verzögerungsbindungsskriptblöcken für den Parameter.
Der Verzögerungsbindungsskriptblock wird während des ParameterBindings automatisch ausgeführt. Das Ergebnis ist an den Parameter gebunden. Die Verzögerungsbindung funktioniert nicht für Parameter, die als Typ ScriptBlock oder System.Objectdefiniert sind. Der Skriptblock wird übergeben, ohne aufgerufen zu werden.
Informationen zu Verzögerungsbindungsskriptblöcken finden Sie hier about_Script_Blocks.md
Akzeptiert Feldhalterzeichen
Diese Einstellung gibt an, ob der Wert des Parameters Einstellzeichen enthalten kann, sodass der Parameterwert mit mehr als einem vorhandenen Element im Zielcontainer abgeglichen werden kann.
Allgemeine Parameter
Allgemeine Parameter sind Parameter, die Sie mit jedem Cmdlet verwenden können. Weitere Informationen zu allgemeinen Parametern finden Sie unter about_CommonParameters.