Hinzufügen einer Cmdlet-Beschreibung

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 im Abschnitt BESCHREIBUNG 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 eine Beschreibung hinzu

Der <maml:description> Knoten enthält die detaillierte Beschreibung des Cmdlets. Dieses Element enthält ein oder mehrere <maml:para> Elemente. Die Beschreibung wird in ein <maml:para> Element eingeschlossen. Das folgende Beispiel zeigt die Struktur des XML-Codes:

<maml:description>
  <maml:para>...</maml:para>
</maml:description>

Tipps zum Schreiben

  • Beginnen Sie, indem Sie die grundlegenden Features des Cmdlets ausführlicher erläutern. In vielen Fällen können Sie die im Cmdlet-Namen verwendeten Begriffe erläutern und unbekannte Konzepte mit einem Beispiel veranschaulichen. Wenn das Cmdlet beispielsweise Daten an eine Datei anfügt, erklären Sie, dass sie Daten am Ende einer vorhandenen Datei hinzufügt.

  • Überprüfen Sie die Parameterliste, um alle Features des Cmdlets zu finden. Beschreiben Sie die primäre Funktion des Cmdlets, und fügen Sie dann weitere Funktionen und Features ein. Wenn beispielsweise die Hauptfunktion des Cmdlets darin besteht, eine Eigenschaft zu ändern, aber das Cmdlet kann alle Eigenschaften ändern, sagen Sie dies in der detaillierten Beschreibung. Wenn die Cmdlet-Parameter den Benutzern das Anfordern von Informationen auf unterschiedliche Weise ermöglichen, erläutern Sie sie.

  • Fügen Sie zusätzlich zu den offensichtlichen Verwendungsmöglichkeiten Informationen hinzu, wie Benutzer das Cmdlet verwenden können. Sie können z. B. das Objekt verwenden, das vom Get-Host Cmdlet abgerufen wird, um die Textfarbe im PowerShell-Befehlsfenster Windows zu ändern.

    Beispiel: "Das Get-Acl Cmdlet ruft Objekte ab, die den Sicherheitsdeskriptor einer Datei oder Ressource darstellen. Der Sicherheitsdeskriptor enthält die Zugriffssteuerungslisten (ACLs) der Ressource. Die ACL gibt die Berechtigungen an, die Benutzer und Benutzergruppen für den Zugriff auf die Ressource haben."

  • Die ausführliche Beschreibung sollte das Cmdlet beschreiben, aber es sollten keine Konzepte beschrieben werden, die das Cmdlet verwendet. Platzieren Sie Konzeptdefinitionen in zusätzlichen Notizen.

Siehe auch

Windows PowerShell SDK

  • Last updated on