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:
| 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:
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:
Output from Get-Help Get-ChildItemDepth
Der Parameter -Examples kann auch verwendet werden, um alle verfügbaren Beispiele auszugeben:
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.
PowerShell-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
Zusammenhängende Posts
Über den Autor:
Philip Lorenz ist als DevOps- und Cloud-Engineer tätig. Neben dieser Tätigkeit hält er Schulungen und erstellt Lerninhalte rund um die Themen PowerShell, Automatisierung und Cloud-Computing.