Jetzt testen

Get-Help! Kommentar-basierte Hilfe in PowerShell-Scripten einsetzen

Inhalt

Post Featured Image

Bestimmt nutzt du bereits Kommentare innerhalb deiner PowerShell-Scripte und bestimmt hast auch du dich schon über unkommentierte Scripte geärgert.

Kommentare in PowerShell-Scripten ermöglichen es, bestimmte Abläufe direkt im Code zu dokumentieren. Des Weiteren können zusätzliche Hinweise zu Code-Ausschnitten hinzugefügt werden – beispielsweise, wenn eine Funktion um weitere Features erweitert werden soll.

Doch über diesen reinen Informationsgehalt hinaus können Kommentare in der PowerShell, richtig angewendet, für Hilfe-Artikel zu deinen Funktionen genutzt werden. In diesem Artikel zeige ich dir, wie du Meta-Daten nutzt, um Script-Informationen per Get-Help zu erhalten.

Comment-Based Help Keywords

Das Zauberwort für unser Vorhaben lautet Comment-Based Help (auf Deutsch: „Kommentar-basierte Hilfe“). Wie der Name schon vermuten lässt, ermöglicht uns dieses Verfahren Hilfe-Informationen durch Kommentare zu generieren. Diese müssen dafür korrekt angeordnet und formatiert sein – wie genau erfährst du in diesem Abschnitt.

Prinzipiell kann man in zwei Arten unterscheiden: Comment-Based Help für Funktionen und für Scripte. Erstere geht eine Schicht tiefer und setzt bei Funktionen an, welche wir mit Metainformationen versehen wollen. Falls dein Code aber nicht in Funktionen aufbereitet ist, ist es auch möglich ein ganzes Script mit diesen Informationen auszustatten.

Bevor wir deren genaue Verwendung betrachten, liste ich hier sämtliche Keywords für die Comment-Based Help auf:

Keywords der Comment-Based Help
KEYWORD FUNCTION
SYNOPSIS Kurzbeschreibung des Scripts oder der Funktion
DESCRIPTION Detaillierte Beschreibung des Codes
PARAMETER Beschreibung eines verwendeten Parameters. Keyword wird mehrfach (1x pro Parameter verwendet). Der Parameter muss nach dem Keyword zusätzlich genannt werden!
INPUTS Beschreibung von möglichen Objekten, die mittels einer Pipeline in die Funktion übergeben werden können.
OUTPUTS Rückgabewerte der Funktion
NOTES Zusätzliche Informationen zum Code
LINK URL zur entsprechenden Online-Hilfe (sofern verfügbar)

Um den Rahmen dieses Artikels nicht zu sprengen, belasse ich die Auflistung bei den Keywords, welche am häufigsten genutzt werden. Weitere Keyword findest du in den Microsoft Docs.

Hinweis: Auch für den Einsatz von Scripten in der ScriptRunner Software Plattform spielen die Script Header-Informationen eine wichtige Rolle. Mehr darüber können Sie hier nachlesen: PowerShell Script Header und Parameter zur Verwendung in ScriptRunner.

Verwenden von Comment-Based Help

Die oben aufgelisteten Keywords werden in einem bestimmten Format im Code

aufgeführt. Dieses sieht wie folgt aus:Screenshot: Darstellung der Notation von Help Keywords und Content im Script

Notation von Help-Keywords und -Inhalten im PowerShell Script Header

Die Keywords werden mit einem Punkt angeführt – die entsprechenden Texte werden unterhalb des Keywords platziert. Der Keyword-Block wird dabei mittels „“ auskommentiert.

Comment-Based Scripts und Functions unterscheiden sich dahingehend, dass der Comment-Block anders platziert wird. Bei Funktionen bietet es sich an, den Block unter den Funktionsnamen zu setzen. Andere Möglichkeiten sind das Setzen des Blocks direkt vor die Funktion (ohne Leerzeile) oder am Ende des Funktions-Bodys.

Sollen Scripte mit den Informationen ausgestattet werden, wird der Comment-Block direkt zu Beginn des Codes gesetzt – logischerweise enthält dieser dann auch Informationen über das Script als Gesamtheit und nicht über Teilausschnitte.

Beispiel und Anwendung von Comment-Based Help

Im Folgenden wird anhand einer Funktion, welche sämtliche Verzeichnis- und Dateiobjekte eines gewissen Verzeichnisses bis zu einer gewissen Hierarchie-Tiefe ausgibt, dargelegt, wie Comment-Based Help in der Praxis angewandt werden kann.

PowerShell stellt diese Funktionalität bereits zur Verfügung – folgendes Beispiel dient lediglich dem Verständnis.

Screenshot: Beispiel PowerShell-Funktion

Beispiel-Funktion

Ziel ist es nun die Wirkungsweise mittels Beschreibungen, Beispielen und Parameter-Informationen in einem Hilfe-Artikel zu beschreiben.

Screenshot: Metainformationen im Header der Funktion

Metainformationen im Funktionsheader

In diesem Code wurde nun ein ganzheitlicher Hilfe-Kommentar geschrieben. Bei einem Get-Help-Aufruf auf diese Information erhalten wir nun in der Konsole die folgende Ausgabe:

PowerShell Screenshot: Ausgabe von Get-Help Get-ChildItemDepth

Output from Get-Help Get-ChildItemDepth

Der Parameter -Examples kann auch verwendet werden, um alle verfügbaren Beispiele auszugeben:

alt="PowerShell Screenshot: Output from Get-Help Get-ChildItemDepth -Examples"

Ausgabe von Get-Help Get-ChildItemDepth

Tipp: Für mehr Beispiele von Scripten, die nach PowerShell Best Practices aufgebaut sind, werfen Sie einen Blick in unsere ScriptRunner ActionPacks.

Fazit

Prinzipiell lässt sich sagen, dass die Comment-Based Help einen großen Mehrwert für IT-Abteilungen bietet. So kann man sich nicht nur selbst schnellen Überblick über die selbstgebauten Funktionen verschaffen, sondern auch Kollegen müssen sich nicht erst durch mehrere Zeilen Code kämpfen, um die Grundfunktionalität zu erahnen.

Der Script-Name kann aufgrund der begrenzten Länge immer nur einen groben Hinweis auf die Funktion eines Scripts geben, ohne auf detaillierte Informationen eingehen zu können. Mit dieser Art der Hilfeerstellung spart man sich außerdem eine externe Dokumentation des Codes.

Sollte eine grundlegende Policy oder ein Code-of-Conduct vorliegen, welche das Verwenden dieser Hilfe-Sektionen ausdrücklich vorschreiben, kann ich eindringlich auf das Pester-Modul verweisen. Dieses kann so konfiguriert werden, dass der Code vor jedem Release auf das Vorhandensein von Hilfe-Artikeln geprüft wird. Es kann sogar nachvollzogen werden, ob jeder einzelne Parameter eine Beschreibung aufweist.


Webinar-PS-ScripteVorlagen_XINGPowerShell-Scripte mit Vorlagen entwickeln

Lernen Sie die Best Practices beim Schreiben von PowerShell-Scripten kennen und erfahren Sie, wie

  • ein Script aufgebaut sein sollte
  • Sie Ihre Scriptsammlung aufbauen
  • Sie Copy-and-paste vermeiden und Codebestandteile und Funktionen mehrfach nutzen können
  • Sie Änderungen vornehmen
  • Sie sicherstellen, dass dies alles auch für Ihr Team nachvollziehbar bleibt

Sehen Sie sich das Webinar kostenlos an > 


Weiterführende Links

Über den Autor: