Hinzufügen des Cmdlet-Namens und der Synopsis zu einem Cmdlet-Hilfethema

Note

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-.

In diesem Abschnitt wird beschrieben, wie Sie Inhalte hinzufügen, die in den Abschnitten NAME und SYNOPSIS der Cmdlet-Hilfe angezeigt werden. In der Hilfedatei wird dieser Inhalt dem Befehlsknoten für jedes Cmdlet hinzugefügt.

Note

Um eine vollständige Ansicht einer Hilfedatei anzuzeigen, öffnen Sie eine der dll-Help.xml Dateien im PowerShell-Installationsverzeichnis. Die Datei enthält z. B Microsoft.PowerShell.Commands.Management.dll-Help.xml . Inhalt für mehrere powerShell-Cmdlets.

So fügen Sie den Cmdlet-Namen und eine Veröffentlichung hinzu

Die Cmdlet-Hilfe kann zwei Beschreibungen für das Cmdlet anzeigen. Die erste Beschreibung ist eine kurze Beschreibung, die als "Synopsis" bezeichnet wird. Die zweite Beschreibung ist eine ausführlichere Beschreibung, die unter Hinzufügen der detaillierten Beschreibung zu einem Cmdlet-Hilfethema erläutert wird. Beide Beschreibungen sollten als einzelner Absatz geschrieben werden.

Der <command:details> Knoten enthält den Cmdlet-Namen und die Synopsis. Der Cmdlet-Name ist in ein <command:name> Element eingeschlossen, und die Synopsis werden in ein <maml:description> Element eingeschlossen. <command:noun> Die <command:verb> Elemente enthalten das Cmdlet-Verb bzw. das Substantiv. Der folgende XML-Code zeigt z. B. den <command:details> Knoten für das Get-ChildItem Cmdlet.

<command:details>
  <command:name>Get-ChildItem</command:name>
  <maml:description>
    <maml:para>Gets the items and child items in one or more specified locations.</maml:para>
  </maml:description>
  <command:verb>Get</command:verb>
  <command:noun>ChildItem</command:noun>
</command:details>

Tipps zum Schreiben

  • Wiederholen Sie in den Synopsis nicht den Cmdlet-Namen. Das Informieren des Benutzers, dass das Get-Server Cmdlet einen Server erhält, ist kurz, aber nicht informativ. Verwenden Sie stattdessen Synonyme, und fügen Sie der Beschreibung Details hinzu.

    Beispiel: "Ruft ein Objekt ab, das einen lokalen oder Remotecomputer darstellt."

  • Verwenden Sie einfache Verben wie "get", "create" und "change" in den Synopsis. Vermeiden Sie die Verwendung von "set", da es vage und ausgefallene Wörter wie "Ändern" ist.

    Beispiel: "Ruft Informationen zur Authenticode-Signatur in einer Datei ab."

  • Schreibe im Aktiv. Beispiel: "Verwenden des TimeSpan-Objekts..." ist viel klarer als "das TimeSpan-Objekt kann verwendet werden, um..."

  • Vermeiden Sie das Verb "display" beim Beschreiben von Cmdlets, die Objekte abrufen. Obwohl Windows PowerShell Cmdlet-Daten anzeigt, ist es wichtig, Benutzern das Konzept vorzustellen, das das Cmdlet .NET Framework-Objekte zurückgibt, deren Daten möglicherweise nicht angezeigt werden. Wenn Sie die Anzeige hervorheben, erkennt der Benutzer möglicherweise nicht, dass das Cmdlet viele andere nützliche Eigenschaften und Methoden zurückgegeben hat, die nicht angezeigt werden.

Siehe auch

Windows PowerShell SDK

  • Last updated on