PowerShell-Module dokumentieren mit PlatyPS
Gestaltwandler
Veröffentlicht in Ausgabe 01/2026 - PRAXIS
Markdown [1] hat sich in den letzten Jahren als Standard für RTF-artige Dokumente etabliert. Dank der weiten Verbreitung des Dateiformats gibt es für so gut wie alle Plattformen entsprechende Editoren mit WYSISWYG-Funktionen. Und der Markdown-MAML-Konverter PlatyPS [2] hilft Administratoren dabei, die für hauseigene PowerShell-Module notwendige Dokumentation mit wenig Aufwand zu generieren.
Inbetriebnahme und Kompatibilitätsprobleme
In den folgenden Schritten arbeiten wir unter Windows 11 mit der PowerShell 7.5.3. Der Quellcode des PlatyPS-Werkzeugs steht auf GitHub [3] zur Verfügung. Gleichzeitig findet sich das Tool mittlerweile in verschiedensten PowerShell-Repositorys. Doch beachten Sie, dass die Eingabe des Befehls
Install-Module -Name platyPS eine veraltete und von Microsoft nicht mehr gewartete Version des Produkts herunterlädt. Für die aktuelle Version verwenden Sie: Install-PSResource -Name Microsoft.PowerShell.PlatyPS
An dieser Stelle konfrontiert Sie die PowerShell mit der üblichen Beschwerde, die über fehlende Vertrauenswürdigkeit des Repositoriums PSGallery informiert. Das Quittieren dieser Sicherheitswarnung ist zur Installation und Inbetriebnahme des Moduls jedoch erforderlich. Behalten Sie daneben im Hinterkopf, dass im MSDN oder der Microsoft-Dokumentation "Microsoft.PowerShell.PlatyPS" auf die aktuelle Version hindeutet, auf "PlatyPS" verweisende Inhalte sind im Allgemeinen für die veraltete Version vorgesehen.
Markdown [1] hat sich in den letzten Jahren als Standard für RTF-artige Dokumente etabliert. Dank der weiten Verbreitung des Dateiformats gibt es für so gut wie alle Plattformen entsprechende Editoren mit WYSISWYG-Funktionen. Und der Markdown-MAML-Konverter PlatyPS [2] hilft Administratoren dabei, die für hauseigene PowerShell-Module notwendige Dokumentation mit wenig Aufwand zu generieren.
Inbetriebnahme und Kompatibilitätsprobleme
In den folgenden Schritten arbeiten wir unter Windows 11 mit der PowerShell 7.5.3. Der Quellcode des PlatyPS-Werkzeugs steht auf GitHub [3] zur Verfügung. Gleichzeitig findet sich das Tool mittlerweile in verschiedensten PowerShell-Repositorys. Doch beachten Sie, dass die Eingabe des Befehls
Install-Module -Name platyPS eine veraltete und von Microsoft nicht mehr gewartete Version des Produkts herunterlädt. Für die aktuelle Version verwenden Sie: Install-PSResource -Name Microsoft.PowerShell.PlatyPS
An dieser Stelle konfrontiert Sie die PowerShell mit der üblichen Beschwerde, die über fehlende Vertrauenswürdigkeit des Repositoriums PSGallery informiert. Das Quittieren dieser Sicherheitswarnung ist zur Installation und Inbetriebnahme des Moduls jedoch erforderlich. Behalten Sie daneben im Hinterkopf, dass im MSDN oder der Microsoft-Dokumentation "Microsoft.PowerShell.PlatyPS" auf die aktuelle Version hindeutet, auf "PlatyPS" verweisende Inhalte sind im Allgemeinen für die veraltete Version vorgesehen.
Im nächsten Schritt folgt der Import von zwei Modulen: einerseits des Dokumentationsgenerators und andererseits eines nicht sonderlich komplizierten "ITATest"-Moduls. Dies haben wir selbst im Vorfeld erstellt, uns dabei jedoch auf das Ausgeben von Meldungen in der Kommandozeile beschränkt und keinen Hilfetext erzeugt, weshalb der Get-Help-Aufruf fehlschlägt.
Erzeugen der Arbeitsdaten-Struktur
Bei PlatyPS sind die für das Erzeugen der Hilfedaten vorgesehenen Befehle zur Reflektion gegen das zu dokumentierende Objekt befähigt. Für die Parametrisierung setzt Microsoft auf eine Struktur, die neben dem Namen des Moduls zusätzliche Felder, beispielsweise mit dem Ausgabeordner, aufnimmt.
Unsere erste Amtshandlung ist das Erzeugen eines Arbeitsverzeichnisses, in dem wir die beiden folgenden Befehle zur Ausführung bringen:
Import-Module -Name Microsoft.PowerShell.PlatyPS
Import-Module -Name ITATest
Nach dem Laden der benötigten Module beginnen wir mit dem Erzeugen der benötigten Daten. Für die eigentliche Generierung der von Hand zu bearbeitenden Markdown-Dateien ist der folgende Code erforderlich:
$helpParams = @{
ModuleInfo = Get-Module ITATest
OutputFolder = '.'
HelpVersion = '1.0.0.0'
WithModulePage = $true
}
New-MarkdownCommandHelp @helpParams
Lohn der Mühen ist die Ausgabe des in Bild 1 gezeigten tabellarischen Berichts, der uns über die generierten Markdown- Dateien informiert. Wir empfehlen im Übrigen beim Einsatz von automatischen Generatoren den Einsatz eines Versionskontrollsystems. Die praktische Erfahrung lehrt, dass selbst der bestmöglich programmierte Generator zum Überschreiben von vom Nutzer in mühevoller Handarbeit angelegten Informationen befähigt ist.
PlatyPS implementiert Dutzende von Parametern, die unter [4] detailliert dokumentiert sind. Für uns ist eine Sondervariante der Parametrierung relevant: Platy- PS kann Dokumentation nur für eine Kommandoliste erzeugen. Dies ist nützlich, wenn nur ein Teil des Moduls zu dokumentieren ist oder Sie eine oder zwei Funktionen zu einem an sich komplett beschriebenen Modul hinzufügen:
$newMarkdownCommandHelpSplat = @{
CommandInfo = Get-Command -Module Microsoft.PowerShell.PlatyPS
Was in den Hilfedateien steckt
Im nächsten Schritt wollen wir die generierten Dateien ansehen: Nummer eins ist "ITATest.md", die das Modul als Ganzes beschreibt. Von PlatyPS generierte Dateien beginnen mit einem Header ("document type: module, Help Version: 1.0.0.0"), der verschiedene Informationen zur Verfügung stellt. Darunter finden sich die einzelnen Beschreibungen. Zu beachten ist, dass die mit "#" eingeleiteten Zellen dem Parser als Einsprungspunkte dienen. Sie dürfen diese nicht verschieben, weil PlatyPS die Markdown-Dateien sonst nicht in das von der PowerShell geforderte Format zurückkonvertieren kann:
# ITATest Module
## Description
{{ Description }}
## ITATest
### [Assert-Fauch](Assert-Fauch.md)
{{ Synopsis }}
### [Assert-Zenz](Assert-Zenz.md)
Die in geschwungenen Klammern gesetzten Elemente sind Platzhalter. Um in der Datei das Modul als Ganzes zu beschreiben tragen Sie dort einfach dessen Funktionalität ein.
Nun wollen wir uns die Methode "Get-NextID" anschauen, die in der PowerShell-Datei vorliegt. Ihr Code weist einen Parameter auf:
function Get-NextID ([int]$startValue = 1) {
$nextID = $startValue
{
; ($script:nextID++)
}.GetNewClosure()
}
Bei der zuvor verwendeten Parametrierung erzeugt PlatyPS für jede Methode eine weitere Markdown-Datei. Das für die Funktion zuständige File "Get-NextID.md" beginnt abermals mit dem Header, der von der Modul-Gesamtbeschreibung bekannt ist:
document type: cmdlet
external help file: ITATest-Help.xml
title: Get-NextID
Zu beachten ist die Nutzung eines anderen "Document Type"-Felds sowie das im vorherigen Beispiel aus Platzgründen nicht abgedruckte Attribut "external help file". Letzteres legt fest, in welcher Datei der aus dem Markdown generierte MAML-Code abzulegen ist. Als Nächstes folgt eine Gruppe von Feldern, die Nutzern des Get-Help-Kommandos schon von der Dokumentation der in der PowerShell eingebauten Kommandos bekannt ist:
# Get-NextID
## SYNOPSIS
{{ Synopsis }}
## SYNTAX
### __AllParameterSets
Get-NextID [[-startValue] <int>]
## ALIASES
Dieses Cmdlet hat die folgenden Aliase,
{{Insert list of aliases}}
## DESCRIPTION
{{ Description }}
Interessant ist der "Examples"-Block: In der Praxis gibt es immer wieder Cmdlets, die mehrere Beispiele aufnehmen. Das Festlegen der Hierarchieebenen der einzelnen Elemente erfolgt durch die Anzahl der "#"-Symbole. Der hier vorliegende Baum hätte als Eltern den String "EXAMPLES", während String "Example 1" das erste Kind-Element darstellt:
## EXAMPLES
### Example 1
{{ Add example description here }}
Für die Dokumentation von Methoden besonders relevant ist der "Parameters"-Block, der sich wie im Listing präsentiert.
Listing: Parameter-Block
## PARAMETERS
### -startValue
{{ Fill startValue Description }}
```yaml
Type: System.Int32
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
Position: 0
IsRequired: false
ValueFromPipeline: false
ValueFromPipelineByPropertyName: false
ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```
## INPUTS
## OUTPUTS
### System.Object
{{ Fill in the Description }}
## NOTES
{{ Fill in the Notes }}
## RELATED LINKS
{{ Fill in the related links here }}
Der mit drei Hochkommata eingeleitete Passus ist ein YAML-Block, in sich Meta-Informationen ablegen lassen. Diese wandern ebenfalls in die MAML-Datei und ermöglichen die von der PowerShell-Ausführungsumgebung bekannte Reflektion und das verbesserte IntelliSense.
Aus dieser Dateistruktur lässt sich der Grund für die erwähnte Spezialparametrierung des Befehls ableiten. Hat sich nur ein Teil des Moduls verändert, können Sie die Neugenerierung der Markup-Dateien beschränken – warum dies wichtig ist, werden wir in den folgenden Schritten feststellen.
Vorher sei allerdings noch auf [5] verwiesen, wo das hinter PlatyPS stehende Entwicklerteam detaillierte Informationen zur Syntax der MD-Dateien zur Verfügung stellt. Bei Fragen zu einzelnen Elementen finden Sie dort schnell Informationen.
Umwandlung in die andere Richtung
Das Generieren von Markdown-Dateien mit Kommentaren zu unserem Testmodell ist kein Selbstzweck. Denn nützlich werden die per PlatyPS generierten Objekte durch das Umwandeln in das MAML-Format. Hierzu steht ein vergleichsweise komplizierter Workflow zur Verfügung, den Bild 2 aufzeigt.
Analog zur Arbeit mit einem Compiler müssen Sie die von PlatyPS generierten Dateien von Hand konvertieren und an den Platz kopieren, wo die PowerShell-Runtime die zum jeweiligen Modul gehörende Hilfe erwartet. Aus dem Aufbau dieses Prozesses folgt, dass Überschreibungen möglich sind. Während das mehrfache Generieren von Markdown in MAML kein Problem darstellt, ist der umgekehrte Weg destruktiv. Bei falscher Parametrisierung kann der New-MarkdownCommandHelp-Befehl manuell eingepflegte Hilfeinformationen zerstören. Wie angesprochen ist ein Versionskontrollsystem unbedingt empfehlenswert; steht dieses nicht zur Verfügung, helfen regelmäßige Backups auf ein externes Medium.
Die Umwandlungsbefehle erwarten Felder als Eingabedaten, die die zu bearbeitenden Dateinamen beschreiben. Zu ihrer Generierung steht das Measure-PlatyPSMarkdown-Cmdlet bereit:
Measure-PlatyPSMarkdown -Path .\*.md
Nach dem Abarbeiten erscheint die in Bild 3 gezeigte Tabelle. Von besonderer Relevanz ist die Spalte "Filetype", die filterbar ist und das Ansprechen der zu konvertierenden Dateien ermöglicht.
Im nächsten Schritt wollen wir eine grundlegende Konversion vorführen, was durch Verkettung und Piping in das Export-MamlCommandHelp-Kommando erfolgt:
Measure-PlatyPSMarkdown -Path .\*.md |
Where-Object Filetype -match 'CommandHelp' |
Import-MarkdownCommandHelp -Path {$_.FilePath} |
Export-MamlCommandHelp -Output Folder .\maml
Dadurch entsteht die Datei "\ITATest\ITATest-Help.xml", die bei der hier gezeigten Parametrisierung im aktuellen Arbeitsverzeichnis des PowerShell-Interpreters unterkommt.
Sodann müssen wir ermitteln, wo die PowerShell-Umgebung die zu unserem Modul gehörenden Hilfedateien erwartet. Dies gelingt via:
(Get-Module -ListAvailable ITATest*).path
Dergestalt werten wir das Path-Attribut aus und erhalten den Aufenthaltsort der PowerShell-Dateien des Moduls in der Kommandozeile. Auf der in den folgenden Schritten verwendeten Maschine handelt es sich dabei um den Pfad "C:\Users \ tamha \ Documents \ PowerShell \ Modules \ ITATest \ ITATest.psm1".
Zu beachten ist, dass die PowerShell mit kulturspezifischen (also Tastaturlayout, die Datums-, Zahlen- und Währungsformate) Hilfedateien arbeitet. Der Befehl
(Get-Culture).Name liefert die hierzu aktuellen Daten aus. In unserem Beispiel lautet der zurückgegebene String "de-DE". Erstes Ziel unserer Suche ist also der Ordner "C:\Users \ tamha \ Documents \ PowerShell \ Modules \ ITATest \ de-DE". Finden sich dort keine Hilfedateien, suchen aktuelle Versionen der PowerShell noch in "en-US".Im nächsten Schritt legen wir den Ordner für die PowerShell-Hilfedatei an. Da wir hier mit einem alleinstehenden PSM1-File arbeiten, ist das Hinzufügen zusätzlicher Header erforderlich. Alle zu dokumentierenden Funktionen müssen wir im Quellcode mit folgendem Attribut ausstatten:
#.EXTERNALHELP ITATest-help.xml
function Assert-Fauch {
Write-Output "Fauch, ich tanze den Tanz Nummer " $myWefzentanz
$global:myWefzentanz = $global:myWefzentanz + 1
}
Nun ist ein Neustart der PowerShell erforderlich und nach dem abermaligen Import liefert das Get-Help-Cmdlet die per PlatyPS generierten Informationen aus. Zu beachten ist, dass eine allgemeine Modulhilfe bei alleinstehenden PSM-Modulen nicht möglich ist und "Get-Help" fehlschlägt. So ist es empfehlenswert, die unter [6] beschriebene Funktion der aktualisierbaren Hilfedateien zu nutzen. Die Dateien liegen in diesem Fall auf einem HTTPS-Server und werden von der PowerShell bei Bedarf heruntergeladen.
Fazit
Die Dokumentation von PowerShell-Modulen ist in vielerlei Hinsicht hilfreich. Mit dem hier vorgestellten PlatyPS-Werkzeug müssen sich Administratoren nicht mit MAML auseinandersetzen, sondern können auf ein weites Ökosystem von Markdown-Verarbeitern zurückgreifen. Dank des wesentlich bequemeren Bearbeitens der Dateien amortisiert sich der Mehraufwand für die Konversion schnell.
(jp)
Links
[1] Markdown-Syntax: https://it-a.eu/q1p31
[2] Microsoft.PowerShell.PlatyPS-Modul: https://it-a.eu/q1p32
[3] PlatyPS auf GitHub: https://it-a.eu/q1p33
[4] New-MarkdownCommand-Help-Cmdlet: https://it-a.eu/q1p34
[5] Markdown-Hilfedateien bearbeiten: https://it-a.eu/q1p35
[6] Konvertieren der Hilfedateien: https://it-a.eu/q1p36