about_Command_Syntax
Kurze Beschreibung
Beschreibt die Syntaxdiagramme, die in PowerShell verwendet werden.
Lange Beschreibung
Die Cmdlets Get-Help und Get-Command zeigen Syntaxdiagramme an, um Befehle richtig zu erstellen. In diesem Thema wird erläutert, wie Die Syntaxdiagramme interpretiert werden.
SYNTAXDIAGRAMME
Jeder Absatz in einem Befehlssyntaxdiagramm stellt eine gültige Form des Befehls dar.
Um einen Befehl zu erstellen, folgen Sie dem Syntaxdiagramm von links nach rechts. Wählen Sie aus den optionalen Parametern aus, und geben Sie Werte für die Platzhalter an.
PowerShell verwendet die folgende Notation für Syntaxdiagramme.
<command-name> -<Required Parameter Name> <Required Parameter Value>
[-<Optional Parameter Name> <Optional Parameter Value>]
[-<Optional Switch Parameters>]
[-<Optional Parameter Name>] <Required Parameter Value>
Es folgt die Syntax für das Cmdlet New-Alias .
New-Alias [-Name] <string> [-Value] <string> [-Description <string>]
[-Force] [-Option {None | ReadOnly | Constant | Private | AllScope}]
[-PassThru] [-Scope <string>] [-Confirm] [-WhatIf] [<CommonParameters>]
Die Syntax wird aus Gründen der Lesbarkeit groß geschrieben, aber bei PowerShell wird die Groß-/Kleinschreibung nicht beachtet.
Das Syntaxdiagramm enthält die folgenden Elemente.
Befehlsname
Befehle beginnen immer mit einem Befehlsnamen, z. B New-Alias. . Geben Sie den Befehlsnamen oder seinen Alias ein, z. B. "gcm" für Get-Command.
Parameter
Die Parameter eines Befehls sind Optionen, die bestimmen, was der Befehl ausführt. Einige Parameter nehmen einen "Wert" an, der als Benutzereingabe für den Befehl verwendet wird.
Der Befehl verfügt beispielsweise über einen Name-Parameter, Get-Help mit dem Sie den Namen des Themas angeben können, für das Hilfe angezeigt wird. Der Themenname ist der Wert des Parameters Name .
In einem PowerShell-Befehl beginnen Parameternamen immer mit einem Bindestrich. Der Bindestrich teilt PowerShell mit, dass das Element im Befehl ein Parametername ist.
Um beispielsweise den Parameter Name von New-Aliaszu verwenden, geben Sie Folgendes ein:
-Name
Parameter können obligatorisch oder optional sein. In einem Syntaxdiagramm werden optionale Elemente in Klammern [ ]eingeschlossen.
Weitere Informationen zu Parametern finden Sie unter about_Parameters.
Parameterwerte
Ein Parameterwert ist die Eingabe, die der Parameter übernimmt. Da Windows PowerShell auf dem Microsoft-.NET Framework basiert, werden Parameterwerte im Syntaxdiagramm durch ihren .NET-Typ dargestellt.
Der Name-Parameter von Get-Help nimmt beispielsweise einen "String"-Wert an, bei dem es sich um eine Textzeichenfolge handelt, z. B. ein einzelnes Wort oder mehrere Wörter, die in Anführungszeichen eingeschlossen sind.
[-Name] <string>
Der .NET-Typ eines Parameterwerts wird in spitzen Klammern < > eingeschlossen, um anzugeben, dass er Platzhalter für einen Wert und nicht ein Literal ist, das Sie in einen Befehl eingeben.
Um den Parameter zu verwenden, ersetzen Sie den Platzhalter des .NET-Typs durch ein Objekt, das über den angegebenen .NET-Typ verfügt.
Um beispielsweise den Parameter Name zu verwenden, geben Sie "-Name" gefolgt von einer Zeichenfolge ein, z. B. die folgende:
-Name MyAlias
Parameter ohne Werte
Einige Parameter akzeptieren keine Eingabe, sodass sie keinen Parameterwert haben. Parameter ohne Werte werden als "Parameter umschalten" bezeichnet, da sie wie Ein-/Aus-Schalter funktionieren. Sie schließen sie (ein) ein oder lassen sie aus einem Befehl aus.
Um einen Switch-Parameter zu verwenden, geben Sie einfach den Parameternamen ein, dem ein Bindestrich vorangestellt ist.
Geben Sie beispielsweise Folgendes ein, um den WhatIf-Parameter des New-Alias Cmdlets zu verwenden:
-WhatIf
Parametersätze
Die Parameter eines Befehls werden in Parametersätzen aufgeführt. Parametersätze sehen wie die Absätze eines Syntaxdiagramms aus.
Das New-Alias Cmdlet verfügt über einen Parametersatz, aber viele Cmdlets verfügen über mehrere Parametersätze. Einige der Cmdletparameter sind für einen Parametersatz eindeutig, andere werden in mehreren Parametersätzen angezeigt. Jeder Parametersatz stellt das Format eines gültigen Befehls dar. Ein Parametersatz enthält nur Parameter, die zusammen in einem Befehl verwendet werden können. Wenn Parameter nicht im selben Befehl verwendet werden können, werden sie in separaten Parametersätzen angezeigt.
Das Cmdlet Get-Random verfügt beispielsweise über die folgenden Parametersätze:
Get-Random [[-Maximum] <Object>] [-Minimum <Object>] [-SetSeed <int>]
[<CommonParameters>]
Get-Random [-InputObject] <Object[]> [-Count <int>] [-SetSeed <int>]
[<CommonParameters>]
Der erste Parametersatz, der eine Zufallszahl zurückgibt, weist die Parameter Minimum und Maximum auf. Der zweite Parametersatz, der ein zufällig ausgewähltes Objekt aus einer Gruppe von Objekten zurückgibt, enthält die Parameter InputObject und Count . Beide Parametersätze verfügen über den SetSeed-Parameter und die allgemeinen Parameter.
Diese Parametersätze geben an, dass Sie die Parameter InputObject und Count im selben Befehl verwenden können, aber sie können die Parameter Maximum und Count nicht im selben Befehl verwenden.
Sie geben an, welchen Parametersatz Sie verwenden möchten, indem Sie die Parameter in diesem Parametersatz verwenden.
Jedes Cmdlet verfügt jedoch auch über einen Standardparametersatz. Der Standardparametersatz wird verwendet, wenn Sie keine Parameter angeben, die für einen Parametersatz eindeutig sind. Wenn Sie beispielsweise ohne Parameter verwendenGet-Random, geht Windows PowerShell davon aus, dass Sie den Parametersatz Number verwenden und eine Zufallszahl zurückgibt.
In jedem Parametersatz werden die Parameter in der Positionsreihenfolge angezeigt. Die Reihenfolge der Parameter in einem Befehl ist nur wichtig, wenn Sie die optionalen Parameternamen weglassen. Wenn Parameternamen weggelassen werden, weist PowerShell Parametern werte nach Position und Typ zu. Weitere Informationen zur Parameterposition finden Sie unter about_Parameters.
Symbole in Syntaxdiagrammen
Das Syntaxdiagramm listet den Befehlsnamen, die Befehlsparameter und die Parameterwerte auf. Außerdem werden Symbole verwendet, um zu zeigen, wie ein gültiger Befehl erstellt wird.
Die Syntaxdiagramme verwenden die folgenden Symbole:
Ein Bindestrich
-gibt einen Parameternamen an. Geben Sie in einem Befehl den Bindestrich unmittelbar vor dem Parameternamen ohne dazwischenliegende Leerzeichen ein, wie im Syntaxdiagramm dargestellt.Geben Sie beispielsweise Folgendes ein, um den Parameter Name von
New-Aliaszu verwenden:-NameSpitzen Klammern
<>geben Platzhaltertext an. Sie geben die spitzen Klammern oder den Platzhaltertext in einem Befehl nicht ein. Stattdessen ersetzen Sie es durch das Element, das darin beschrieben wird.Winkelklammern werden verwendet, um den .NET-Typ des Werts zu identifizieren, den ein Parameter verwendet. Wenn Sie beispielsweise den Parameter Name des
New-AliasCmdlets verwenden möchten, ersetzen Sie durch eine Zeichenfolge, bei der<string>es sich um ein einzelnes Wort oder eine Gruppe von Wörtern handelt, die in Anführungszeichen eingeschlossen sind.Klammern
[ ]zeigen optionale Elemente an. Ein Parameter und sein Wert können optional oder der Name eines erforderlichen Parameters optional sein.Beispielsweise werden der Description-Parameter von
New-Aliasund sein Wert in Klammern eingeschlossen, da beide optional sind.[-Description <string>]Die Klammern geben auch an, dass der Name-Parameterwert
<string>erforderlich ist, der Parametername "Name" jedoch optional ist.[-Name] <string>Eine an einen .NET-Typ angefügte rechte und linke Klammer
[]gibt an, dass der Parameter einen oder mehrere Werte dieses Typs akzeptieren kann. Geben Sie die Werte in eine durch Kommas getrennte Liste ein.Beispielsweise nimmt der Name-Parameter des
New-AliasCmdlets nur eine Zeichenfolge an, aber der Name-Parameter von Get-Process kann eine oder mehrere Zeichenfolgen annehmen.New-Alias [-Name] <string> New-Alias -Name MyAliasGet-Process [-Name] <string[]> Get-Process -Name Explorer, Winlogon, ServicesKlammern
{}geben eine "Enumeration" an, bei der es sich um einen Satz gültiger Werte für einen Parameter handelt.Die Werte in den Klammern sind durch vertikale Balken
|getrennt. Diese Balken weisen auf eine "exklusive OR"-Auswahl hin, was bedeutet, dass Sie nur einen Wert aus dem Satz von Werten auswählen können, die in den Klammern aufgeführt sind.Die Syntax für das
New-AliasCmdlet enthält beispielsweise die folgende Wertaufzählung für den Option-Parameter :-Option {None | ReadOnly | Constant | Private | AllScope}Die Klammern und vertikalen Balken geben an, dass Sie einen der aufgeführten Werte für den Option-Parameter auswählen können, z. B. "ReadOnly" oder "AllScope".
-Option ReadOnly
Optionale Elemente
Klammern [] umgeben optionale Elemente. In der Cmdletsyntaxbeschreibung New-Alias ist beispielsweise der Scope-Parameter optional. Dies wird in der Syntax durch die Klammern um den Parameternamen und -typ angegeben:
[-Scope <string>]
In den beiden folgenden Beispielen wird das New-Alias Cmdlet richtig verwendet:
New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd -Value Update-TypeData -Scope Global
Ein Parametername kann optional sein, auch wenn der Wert für diesen Parameter erforderlich ist. Dies wird in der Syntax durch die Klammern um den Parameternamen, aber nicht den Parametertyp angegeben, wie in diesem Beispiel aus dem New-Alias Cmdlet:
[-Name] <string> [-Value] <string>
Die folgenden Befehle verwenden das New-Alias Cmdlet ordnungsgemäß. Die Befehle erzeugen das gleiche Ergebnis.
New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd Update-TypeData
New-Alias utd -Value Update-TypeData
New-Alias utd Update-TypeData
Wenn der Parametername nicht als typisiert in der Anweisung enthalten ist, versucht Windows PowerShell, die Position der Argumente zu verwenden, um die Werte Parametern zuzuweisen.
Das folgende Beispiel ist nicht abgeschlossen:
New-Alias utd
Für dieses Cmdlet sind Werte für den Parameter Name und Wert erforderlich.
In Syntaxbeispielen werden Klammern auch beim Benennen und Umwandeln in .NET Framework Typen verwendet. In diesem Kontext weisen Klammern nicht darauf hin, dass ein Element optional ist.