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:

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:

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.

Beispiel-Funktion

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

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: