Kommentarbasierte Hilfe - Skriptdokumentationen in das Powershell-Hilfesystem integrieren

Um eine Hilfe für Powershell-Skripte nahtlos zu integrieren, brauchen Sie oberhalb Ihres Parameter-Blocks nur ein Kommentarfeld unterzubringen, das einer fixen Struktur entsprechen muss:

<#
.Synopsis 
Kurzbeschreibung

.DESCRIPTION
Eine ausführliche Beschreibung

.EXAMPLE
Ein Beispiel

.EXAMPLE
Ein weiteres Beispiel

.INPUTS
Übergabewerte

.OUTPUTS
Was das Skript zurück liefert

.NOTES
Allgemeine Informationen wie Autor, Version, Datum

.FUNCTIONALITY
The functionality that best describes this cmdlet 
#>

Param(
   # Die Beschreibung des Parameters [parameter(mandatory=$true)] 
   [string]$Path
)

Sie müssen nicht alle hier angegebenen Stichworte (die Zeilen, die mit einem Punkt beginnen) verwenden. Jeder einzelne Wert ist optional, und es handelt sich auch nicht um die vollständige Liste. Beachten Sie auch den Kommentar, der direkt über dem Parameter $Path steht. Er wird in der Hilfe als Beschreibung des Parameters angezeigt.

Wenn Sie das Skript unter einem beliebigen Namen speichern, können Sie aus dem Skriptordner heraus mit Get-Help die Hilfe zu Ihrem Skript aufrufen.

Get-Help .\CommentBasedHelp.ps1 -ShowWindow

Abbildung 13 - Der Kommentarblock wird als Hilfe angezeigt.

Sie können unter Übersicht die Zusammenfassung (Synopsis) sehen, die Beschreibung des Parameters -Path umfasst den Datenyp, zeigt an, dass der Parameter erforderlich ist, und der Kommentar zum Parameter ist hier als Beschreibung angegeben. Weiter unten im Fenster finden Sie auch Ihre Beispiele wieder.

Die Beschreibung sämtlicher Schlüsselwörter, die Sie im Kommentarblock verwenden können, beschreibt Microsoft in der Powershell-Hilfe im Artikel About_commentbased_help:

get-help about_Comment_Based_Help -ShowWindow

Sollte die Kommentarbasierte Hilfe bei Ihnen nicht funktionieren, könnte das daran liegen, dass die Hilfe nur in sogenannten erweiterten Funktionen zur Verfügung steht. Damit eine Funktion (oder ein Skript) erweitert ist, muss entweder mindestens einer der Parameter mit einem Parameter-Attribut beschrieben werden (im Beispiel durch [parameter(mandatory=$true)] vor dem $Path-Parameter), oder alternativ muss direkt über dem Param-Block noch das Attribut [cmdletbinding()] gesetzt sein:

<#
.Synopsis 
Kurzberschreibung 
#>

Cmdletbinding() 
Param( 
   [String]$Path
)

[Cmdletbinding()] ist übrigens ein Attribut für den Parameter-Block, stellt also keine Ausnahme von der Regel dar, dass über dem Parameter-Block keine Befehle stehen dürfen.