Hinzufügen von Parameterinformationen

In diesem Abschnitt wird beschrieben, wie Sie Inhalte hinzufügen, die im Abschnitt PARAMETER des Cmdlet-Hilfethemas angezeigt werden. Im Abschnitt PARAMETERS des Hilfethemas werden die einzelnen Parameter des Cmdlets aufgeführt, und es wird eine ausführliche Beschreibung der einzelnen Parameter angegeben.

Der Inhalt des Parameters-Abschnitts sollte mit dem Inhalt des Abschnitts SYNTAX des Hilfethemas übereinstimmen. Es liegt in der Verantwortung des Hilfeautors, sicherzustellen, dass sowohl der Syntax- als auch der Parameterknoten ähnliche XML-Elemente enthalten.

Hinweis

Öffnen Sie eine der Dateien im PowerShell-Installationsverzeichnis, um eine vollständige Ansicht dll-Help.xml einer Hilfedatei zu erhalten. Die Datei enthält Microsoft.PowerShell.Commands.Management.dll-Help.xml beispielsweise Inhalt für einige der PowerShell-Cmdlets.

So fügen Sie Parameter hinzu

  1. Öffnen Sie die Hilfedatei des Cmdlets, und suchen Sie den Knoten Befehl für das Cmdlet, das Sie dokumentieren. Wenn Sie ein neues Cmdlet hinzufügen, müssen Sie einen neuen Befehlsknoten erstellen. Ihre Hilfedatei enthält einen Befehlsknoten für jedes Cmdlet, für das Sie Hilfeinhalte bereitstellen. Hier sehen Sie ein Beispiel für einen leeren Befehlsknoten.

    <command:command>
</command:command>

  2. Suchen Sie im Knoten Befehl nach dem Knoten Beschreibung, und fügen Sie wie unten gezeigt einen Parameterknoten hinzu. Es ist nur ein Parameterknoten zulässig, und er sollte unmittelbar auf den Knoten Syntax folgen.

    <command:command>
  <command:details></command:details>
  <maml:description></maml:description>
  <command:syntax></command:syntax>
  <command:parameters>
  </command:parameters>
</command:command>

  3. Fügen Sie im Knoten Parameter einen Parameterknoten für jeden Parameter des Cmdlets hinzu, wie unten gezeigt.

    In diesem Beispiel wird ein Parameterknoten für drei Parameter hinzugefügt.

    <command:parameters>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
</command:parameters>

    Da es sich dabei um die gleichen XML-Tags handelt, die im Knoten Syntax verwendet werden, und da die hier angegebenen Parameter mit den vom Knoten Syntax angegebenen Parametern übereinstimmen müssen, können Sie die Parameterknoten aus dem Knoten Syntax kopieren und in den Knoten Parameter einfügen. Achten Sie jedoch darauf, nur eine Instanz eines Parameterknotens zu kopieren, auch wenn der Parameter in mehreren Parametersätzen in der Syntax angegeben ist.

  4. Legen Sie für jeden Parameterknoten die Attributwerte fest, die die Eigenschaften der einzelnen Parameter definieren. Zu diesen Attributen gehören: required, globbing, pipelineinput und position.

    <command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
  </command:parameter>
  <command:parameter required="false" globbing="false"
           pipelineInput="false" position="named">
  </command:parameter>
  <command:parameter required="false" globbing="false"
           pipelineInput="false" position="named" ></command:parameter>
</command:parameters>

  5. Fügen Sie für jeden Parameterknoten den Namen des Parameters hinzu. Im Folgenden finden Sie ein Beispiel für den Parameternamen, der dem Parameterknoten hinzugefügt wurde.

    <command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
  </command:parameter>
</command:parameters>

  6. Fügen Sie für jeden Parameterknoten die Beschreibung des Parameters hinzu. Im Folgenden finden Sie ein Beispiel für die Parameterbeschreibung, die dem Knoten Parameter hinzugefügt wurde.

    <command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
  </command:parameter>
</command:parameters>

  7. Fügen Sie für jeden Parameterknoten den .NET-Typ des Parameters hinzu. Der Parametertyp wird zusammen mit dem Parameternamen angezeigt.

    Im Folgenden finden Sie ein Beispiel für den .NET-Parametertyp, der dem Parameterknoten hinzugefügt wurde.

    <command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
    <dev:type> Add .NET Framework type... </dev:type>
  </command:parameter>
</command:parameters>

  8. Fügen Sie für jeden Parameterknoten den Standardwert des Parameters hinzu. Der folgende Satz wird der Parameterbeschreibung hinzugefügt, wenn der Inhalt angezeigt wird: DefaultValue ist der Standardwert.

    Im Folgenden finden Sie ein Beispiel für den Parameter-Standardwert, der dem Parameterknoten hinzugefügt wird.

    <command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
    <dev:type> Add .NET Framework type... </dev:type>
    <dev:defaultvalue> Add default value...</dev:defaultvalue>
  </command:parameter>
</command:parameters>

  9. Fügen Sie für jeden Parameter mit mehreren Werten einen possibleValues-Knoten hinzu.

    Im Folgenden finden Sie ein Beispiel für den eines possibleValues-Knotens, der zwei mögliche Werte für den Parameter definiert.

    <dev:possibleValues>
  <dev:possibleValue>
    <dev:value>Unknown</dev:value>
    <maml:description>
      <maml:para></maml:para>
    </maml:description>
  </dev:possibleValue>
  <dev:possibleValue>
    <dev:value>String</dev:value>
    <maml:description>
      <maml:para></maml:para>
    </maml:description>
  </dev:possibleValue>
</dev:possibleValues>

Hier sind einige Dinge, die Sie beim Hinzufügen von Parametern beachten sollten.

  • Die Attribute des Parameters werden nicht in allen Ansichten des Cmdlet-Hilfethemas angezeigt. Sie werden jedoch in einer Tabelle nach der Parameterbeschreibung angezeigt, wenn der Benutzer die Ansicht Full ( ) oder Get-Help <cmdletname> -Full Parameter ( ) Get-Help <cmdletname> -Parameter des Themas angibt.

  • Die Parameterbeschreibung ist einer der wichtigsten Teile eines Cmdlet-Hilfethemas. Die Beschreibung sollte kurz und gründlich sein. Denken Sie außerdem daran, dass Sie im Abschnitt NOTES des Cmdlet-Hilfethemas weitere Inhalte hinzufügen können, wenn die Parameterbeschreibung zu lang wird, z. B. wenn zwei Parameter miteinander interagieren.

    Die Parameterbeschreibung enthält zwei Arten von Informationen.

  • Was das Cmdlet bei Verwendung des Parameters macht.

  • Was ein rechtlicher Wert für den Parameter ist.

  • Da die Parameterwerte als .NET-Objekte ausgedrückt werden, benötigen Benutzer mehr Informationen zu diesen Werten als in einer herkömmlichen Befehlszeilenhilfe. Teilen Sie dem Benutzer mit, welche Art von Daten der Parameter akzeptieren soll, und geben Sie Beispiele an.

Der Standardwert des Parameters ist der Wert, der verwendet wird, wenn der Parameter nicht in der Befehlszeile angegeben wird. Beachten Sie, dass der Standardwert optional ist und für einige Parameter, z. B. erforderliche Parameter, nicht erforderlich ist. Sie sollten jedoch einen Standardwert für die meisten optionalen Parameter angeben.

Der Standardwert hilft dem Benutzer, die Auswirkungen zu verstehen, wenn der Parameter nicht verwendet wird. Beschreiben Sie den Standardwert sehr genau, z. B. das "Aktuelle Verzeichnis" oder das "PowerShell-Installationsverzeichnis ( $PSHOME )" für einen optionalen Pfad. Sie können auch einen Satz schreiben, der den Standardwert beschreibt, z. B. den folgenden Satz, der für den PassThru-Parameter verwendet wird: "Wenn PassThru nicht angegeben ist, übergibt das Cmdlet keine Objekte an die Pipeline." Da der Wert gegenüber dem Feldnamen Standardwert angezeigt wird, müssen Sie den Begriff "Standardwert" nicht in den Eintrag eingeben.

Der Standardwert des Parameters wird nicht in allen Ansichten des Cmdlet-Hilfethemas angezeigt. Sie wird jedoch in einer Tabelle (zusammen mit den Parameterattributen) angezeigt, die der Parameterbeschreibung folgt, wenn der Benutzer die Ansicht Full ( ) oder Parameter ( ) des Themas Get-Help <cmdletname> -Full Get-Help <cmdletname> -Parameter angibt.

Der folgende XML-Code zeigt ein Paar von <dev:defaultValue> Tags, die dem Knoten hinzugefügt <command:parameter> wurden. Beachten Sie, dass der Standardwert unmittelbar nach dem schließenden Tag (wenn der Parameterwert angegeben wird) oder dem schließenden </command:parameterValue> </maml:description> Tag der Parameterbeschreibung folgt. name.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
  </command:parameter>
</command:parameters>

Hinzufügen von Werten für aufzählte Typen

Wenn der Parameter über mehrere Werte oder Werte eines aufzählten Typs verfügt, können Sie einen optionalen Knoten <dev:possibleValues> verwenden. Mit diesem Knoten können Sie einen Namen und eine Beschreibung für mehrere Werte angeben.

Beachten Sie, dass die Beschreibungen der aufzählten Werte nicht in den standardmäßigen Hilfeansichten angezeigt werden, die vom Cmdlet angezeigt werden, aber andere Help Viewer können diesen Inhalt in ihren Ansichten Get-Help anzeigen.

Der folgende XML-Code zeigt <dev:possibleValues> einen Knoten mit zwei angegebenen Werten.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
    <dev:possibleValues>
      <dev:possibleValue>
        <dev:value> Value 1 </dev:value>
        <maml:description>
          <maml:para> Description 1 </maml:para>
        </maml:description>
      <dev:possibleValue>
      <dev:possibleValue>
        <dev:value> Value 2 </dev:value>
        <maml:description>
          <maml:para> Description 2 </maml:para>
        </maml:description>
      <dev:possibleValue>
    </dev:possibleValues>
  </command:parameter>
</command:parameters>
  • Last updated on