So fügen Sie einem Hilfethema zum Cmdlet Syntax hinzu

Hinweis

Die manuelle Erstellung von XML-basierten Hilfen ist sehr schwierig. Mit dem PlatyPS Modul können Sie Hilfe in Markdown schreiben und dann in XML-basierte Hilfe konvertieren. Dies erleichtert das Schreiben und Verwalten von Hilfe. PlatyPS- können auch die aktualisierbaren Hilfepakete für Sie erstellen. Weitere Informationen finden Sie unter Erstellen einer XML-basierten Hilfe mithilfe von PlatyPS-.

Bevor Sie mit dem Codieren des XML-Codes für das Syntaxdiagramm in der Cmdlet-Hilfedatei beginnen, lesen Sie diesen Abschnitt, um ein klares Bild der Art von Daten zu erhalten, die Sie bereitstellen müssen, z. B. die Parameterattribute und die Darstellung dieser Daten im Syntaxdiagramm.

Parameterattribute

Erforderlich
- Wenn true, muss der Parameter in allen Befehlen angezeigt werden, die den Parametersatz verwenden.
- Wenn false, ist der Parameter in allen Befehlen optional, die den Parametersatz verwenden.
Position
- Wenn der Name benannt wird, ist der Parametername erforderlich.
- Wenn positional, ist der Parametername optional. Wenn er weggelassen wird, muss sich der Parameterwert an der angegebenen Position im Befehl befinden. Wenn der Wert beispielsweise "position="1" lautet, muss der Parameterwert der erste oder nur unbenannte Parameterwert im Befehl sein.
Pipelineeingabe
- Wenn true (ByValue), können Sie Eingaben an den Parameter übergeben. Die Eingabe ist dem Parameter ("gebunden an") zugeordnet, auch wenn der Eigenschaftenname und der Objekttyp nicht mit dem erwarteten Typ übereinstimmen. Die PowerShell-Parameterbindungskomponenten versuchen, die Eingabe in den richtigen Typ zu konvertieren, und schlagen den Befehl nur fehl, wenn der Typ nicht konvertiert werden kann. Nur ein Parameter in einem Parametersatz kann nach Wert zugeordnet werden.
- Wenn true (ByPropertyName), können Sie Eingaben an den Parameter übergeben. Die Eingabe ist dem Parameter jedoch nur zugeordnet, wenn der Parametername dem Namen einer Eigenschaft des Eingabeobjekts entspricht. Wenn der Parametername beispielsweise Pathist, werden objekte, die an das Cmdlet weitergeleitet werden, nur zugeordnet, wenn das Objekt über eine Eigenschaft mit dem Namen pfad verfügt.
- Wenn true (ByValue, ByPropertyName), können Sie Eingaben an den Parameter entweder anhand des Eigenschaftennamens oder des Werts senden. Nur ein Parameter in einem Parametersatz kann nach Wert zugeordnet werden.
- Wenn false, können Sie keine Eingabe an diesen Parameter übergeben.
Globbing
- Wenn true, kann der Text, den der Benutzer für den Parameterwert eingibt, Wildcardzeichen enthalten.
- Wenn false, kann der Text, den der Benutzer für den Parameterwert eingibt, keine Wildcardzeichen enthalten.

Parameterwertattribute

Erforderlich
- Wenn true, muss der angegebene Wert immer verwendet werden, wenn der Parameter in einem Befehl verwendet wird.
- Bei "false" ist der Parameterwert optional. In der Regel ist ein Wert nur optional, wenn es sich um einen von mehreren gültigen Werten für einen Parameter handelt, z. B. in einem Aufzählungstyp.

Das attribut Required eines Parameterwerts unterscheidet sich vom attribut Required eines Parameters.

Das erforderliche Attribut eines Parameters gibt an, ob der Parameter (und sein Wert) beim Aufrufen des Cmdlets eingeschlossen werden muss. Im Gegensatz dazu wird das erforderliche Attribut eines Parameterwerts nur verwendet, wenn der Parameter im Befehl enthalten ist. Es gibt an, ob dieser bestimmte Wert mit dem Parameter verwendet werden muss.

Parameterwerte, die Platzhalter sind, sind in der Regel erforderlich und Parameterwerte, die Literal sind nicht erforderlich, da sie einer von mehreren Werten sind, die mit dem Parameter verwendet werden können.

Sammeln von Syntaxinformationen

Beginnen Sie mit dem Cmdlet-Namen.
```
SYNTAX
    Get-Tech
```
Listet alle Parameter des Cmdlets auf. Geben Sie vor jedem Parameternamen einen Bindestrich (-) ein. Trennen Sie die Parameter in Parametersätze (einige Cmdlets haben möglicherweise nur einen Parametersatz). In diesem Beispiel weist das Cmdlet Get-Tech zwei Parametersätze auf.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Starten Sie jeden Parametersatz mit dem Cmdlet-Namen.

Listen Sie zuerst den Standardparametersatz auf. Der Standardparameter wird von der Cmdlet-Klasse angegeben.

Listen Sie für jeden Parametersatz zuerst ihren eindeutigen Parameter auf, es sei denn, es gibt Positionsparameter, die zuerst angezeigt werden müssen. Im vorherigen Beispiel sind die Parameter Name und ID eindeutige Parameter für die beiden Parametersätze (jeder Parametersatz muss einen Parameter enthalten, der für diesen Parametersatz eindeutig ist). Dadurch können Benutzer leichter identifizieren, welcher Parameter für den Parametersatz angegeben werden muss.

Listen Sie die Parameter in der Reihenfolge auf, in der sie im Befehl angezeigt werden sollen. Wenn die Reihenfolge keine Rolle spielt, listen Sie verwandte Parameter zusammen auf, oder listen Sie zuerst die am häufigsten verwendeten Parameter auf.

Stellen Sie sicher, dass Sie die Parameter WhatIf und Confirm auflisten, wenn das Cmdlet ShouldProcess unterstützt.

Listen Sie die allgemeinen Parameter (z. B. Verbose, Debug und ErrorAction) nicht in Ihrem Syntaxdiagramm auf. Das Cmdlet Get-Help fügt diese Informationen für Sie hinzu, wenn das Hilfethema angezeigt wird.
Fügen Sie die Parameterwerte hinzu. In PowerShell werden Parameterwerte durch ihren .NET-Typ dargestellt. Der Typname kann jedoch abgekürzt werden, z. B. "string" für "System.String".
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
Abkürzungstypen, solange ihre Bedeutung klar ist, z. B. Zeichenfolgen für System.String- und int für System.Int32.

Listet alle Werte von Enumerationen auf, z. B. den parameter -Type im vorherigen Beispiel, der auf grundlegenden oder erweitertenfestgelegt werden kann.

Schalterparameter, z. B. -List im vorherigen Beispiel, weisen keine Werte auf.
Fügen Sie Winkelklammern zu Parameterwerten hinzu, die Platzhalter sind, im Vergleich zu Parameterwerten, die Literale sind.
```
SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced
```

Schließen Sie optionale Parameter und deren Werte in eckige Klammern ein.

SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

Schließen Sie optionale Parameternamen (für Positionsparameter) in eckige Klammern ein. Der Name für Parameter, die positional sind, z. B. der Name-Parameter im folgenden Beispiel, müssen nicht in den Befehl eingeschlossen werden.
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
Wenn ein Parameterwert mehrere Werte enthalten kann, z. B. eine Liste von Namen im Parameter Name, fügen Sie ein Paar eckige Klammern direkt nach dem Parameterwert hinzu.
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
Wenn der Benutzer aus Parametern oder Parameterwerten wählen kann, z. B. den Type-Parameter, schließen Sie die Auswahl in geschweifte Klammern ein, und trennen Sie sie mit dem exklusiven OR-Symbol(;)).
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```
Wenn der Parameterwert bestimmte Formatierungen verwenden muss, z. B. Anführungszeichen oder Klammern, zeigen Sie das Format in der Syntax an.
```
SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

Codieren des Syntaxdiagramms XML

Der Syntaxknoten des XML-Codes beginnt unmittelbar nach dem Beschreibungsknoten, der mit dem </maml:description>-Tag endet. Informationen zum Sammeln der im Syntaxdiagramm verwendeten Daten finden Sie unter Sammeln von Syntaxinformationen.

Hinzufügen eines Syntaxknotens

Das im Hilfethema des Cmdlets angezeigte Syntaxdiagramm wird aus den Daten im Syntaxknoten des XML-Codes generiert. Der Syntaxknoten wird in ein Paar <command:syntax> Tags eingeschlossen. Bei jedem Parametersatz des Cmdlets, das in ein Paar <command:syntaxitem> Tags eingeschlossen ist. Es gibt keine Beschränkung auf die Anzahl der <command:syntaxitem> Tags, die Sie hinzufügen können.

Das folgende Beispiel zeigt einen Syntaxknoten mit Syntaxelementknoten für zwei Parametersätze.

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

Hinzufügen des Cmdlet-Namens zu den Parametersatzdaten

Jeder Parametersatz des Cmdlets wird in einem Syntaxelementknoten angegeben. Jeder Syntaxelementknoten beginnt mit einem Paar <maml:name> Tags, die den Namen des Cmdlets enthalten.

Das folgende Beispiel enthält einen Syntaxknoten mit Syntaxelementknoten für zwei Parametersätze.

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

Hinzufügen von Parametern

Jeder Parameter, der dem Syntaxelementknoten hinzugefügt wird, wird innerhalb eines Paars von <command:parameter> Tags angegeben. Sie benötigen ein Paar <command:parameter> Tags für jeden Parameter, der im Parametersatz enthalten ist, mit Ausnahme der allgemeinen Parameter, die von PowerShell bereitgestellt werden.

Die Attribute des öffnenden <command:parameter> Tags bestimmen, wie der Parameter im Syntaxdiagramm angezeigt wird. Informationen zu Parameterattributen finden Sie unter Parameterattribute.

Hinweis

Das <command:parameter>-Tag unterstützt ein untergeordnetes Element <maml:description> dessen Inhalt nie angezeigt wird. Die Parameterbeschreibungen werden im Parameterknoten des XML-Codes angegeben. Um Inkonsistenzen zwischen den Informationen im Syntaxelement Bodes und dem Parameterknoten zu vermeiden, weglassen Sie die (<maml:description> oder lassen Sie sie leer.

Das folgende Beispiel enthält einen Syntaxelementknoten für einen Parametersatz mit zwei Parametern.

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>

Feedback

War diese Seite hilfreich?

Last updated on 2025-03-25