Freigeben über

Schreiben von Hilfe zu PowerShell-Modulen

PowerShell-Module können Hilfethemen zum Modul und zu den Modulmitgliedern enthalten, z. B. Cmdlets, Anbieter, Funktionen und Skripts. Das Get-Help Cmdlet zeigt die Modulhilfethemen im selben Format an wie die Hilfe für andere PowerShell-Elemente, und Benutzer verwenden Standardbefehle Get-Help , um die Hilfethemen abzurufen.

Dieses Dokument erläutert das Format und die richtige Platzierung von Modulhilfethemen und schlägt Richtlinien für Modulhilfeinhalte vor.

Typen der Modulhilfe

Ein Modul kann die folgenden Typen von Hilfe enthalten.

  • XML-basierte Hilfe

    • Cmdlet-Hilfe. Die Hilfethemen, die Cmdlets in einem Modul beschreiben, sind XML-Dateien, die das Befehlshilfeschema verwenden.
    • Anbieterhilfe. Die Hilfethemen, die Anbieter in einem Modul beschreiben, sind XML-Dateien, die das Anbieterhilfeschema verwenden.
    • Funktionshilfe. Die Hilfethemen, die Funktionen in einem Modul beschreiben, können XML-Dateien sein, die das Befehlshilfeschema oder kommentarbasierte Hilfethemen innerhalb der Funktion oder das Skript- oder Skriptmodul verwenden.
    • Skripthilfe. Die Hilfethemen, die Skripts in einem Modul beschreiben, können XML-Dateien sein, die das Befehlshilfeschema oder kommentarbasierte Hilfethemen im Skript- oder Skriptmodul verwenden.
    • Der $PSHOME\Schemas\PSMaml Ordner enthält die Schemadateien, die das XML-Format definieren.

  • Konzeptionelle ("Info")-Hilfedateien

    Sie können ein konzeptionelles Hilfethema ("Info") verwenden, um das Modul und dessen Member zu beschreiben und zu erläutern, wie die Mitglieder zusammen verwendet werden können, um Aufgaben auszuführen. Standardmäßig enthält PowerShell mehr als 100 dieser konzeptionellen Themen zu Hilfethemen. Der Dateiname muss das about_<name>.help.txt Format verwenden, z about_MyModule.help.txt. B. .

    Hinweis

    Die TOPIC Abschnittsüberschrift muss in der ersten Spalte der ersten Zeile der Datei beginnen. Der Abschnittsinhalt in der zweiten Zeile sollte mit dem Dateinamen ohne Suffix .help.txt übereinstimmen. Sie müssen den Inhalt genau 4 Leerzeichen einziehen. Die dritte Zeile muss leer sein. Die SYNOPSIS Abschnittsüberschrift muss in der ersten Spalte der vierten Zeile beginnen. Sie müssen den Inhalt in der fünften Zeile genau 4 Leerzeichen einziehen. Diese Anforderungen sind erforderlich, damit der Get-Help Inhalt vom Cmdlet richtig erkannt wird.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    Sie können die folgende Beispielvorlage als Ausgangspunkt zum Schreiben konzeptioneller Hilfethemen verwenden. Mit Ausnahme der ersten beiden Abschnitte ist die Struktur konzeptioneller Hilfethemen beliebig. Die restlichen Abschnittstitel können für Ihre Inhalte geeignet sein.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    Sie können beliebige Formatvorlagen und Markups verwenden, aber PowerShell sieht sie als Nur-Text und es gibt kein spezielles Rendering des Texts in der PowerShell-Konsole. Die folgenden Vorschläge stellen die besten Anzeigeergebnisse und Lesbarkeit sicher.

    • Verwenden Sie UTF-8 mit BOM-Codierung, um sicherzustellen, dass alle speziellen Zeichen (Multibyte-Zeichen) ordnungsgemäß angezeigt werden.
    • Unterstreichen von Abschnittsüberschriften oder Verwenden aller Großbuchstaben, um sie hervorzuheben. Dies erleichtert das Scannen des Inhalts.
    • Beschränken Sie die Länge jeder Zeile auf 80 Zeichen.
    • Einzugscodeblöcke und Beispielausgabe, um sie von der umgebenden Prose zu trennen.

Platzierung der Modulhilfe

Das Get-Help Cmdlet sucht nach Modulhilfethemadateien in sprachspezifischen Unterverzeichnissen des Modulverzeichnisses.

Das folgende Verzeichnisstrukturdiagramm zeigt beispielsweise den Speicherort der Hilfethemen für das SampleModule-Modul.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Hinweis

Im Beispiel stellt der <ModulePath> Platzhalter einen der Pfade in der PSModulePath Umgebungsvariable dar, z $HOME\Documents\Modules. B. , $PSHOME\Modulesoder einen benutzerdefinierten Pfad, den der Benutzer angibt.

Hilfe zum Abrufen von Modulen

Wenn ein Benutzer ein Modul in eine Sitzung importiert, werden die Hilfethemen für dieses Modul zusammen mit dem Modul in die Sitzung importiert. Sie können die Hilfethemadateien im Wert des FileList-Schlüssels im Modulmanifest auflisten, aber Hilfethemen sind vom Cmdlet nicht betroffen Export-ModuleMember .

Sie können Modulhilfethemen in verschiedenen Sprachen bereitstellen. Das Get-Help Cmdlet zeigt automatisch Modulhilfethemen in der Sprache an, die für den aktuellen Benutzer im Element "Regions- und Sprachoptionen" in der Systemsteuerung angegeben ist. Suchen Sie in Windows Vista und höheren Versionen von Windows Get-Help nach den Hilfethemen in sprachspezifischen Unterverzeichnissen des Modulverzeichnisses gemäß den für Windows festgelegten Sprachfallbackstandards.

Ab PowerShell 3.0 löst das Ausführen eines Get-Help Befehls für ein Cmdlet oder eine Funktion den automatischen Import des Moduls aus. Das Get-Help Cmdlet zeigt sofort den Inhalt der Hilfethemen im Modul an.

Wenn das Modul keine Hilfethemen enthält und es keine Hilfethemen für die Befehle im Modul auf dem Computer des Benutzers gibt, Get-Help werden automatisch generierte Hilfen angezeigt. Die automatisch generierte Hilfe enthält die Befehlssyntax, Parameter und Eingabe- und Ausgabetypen, enthält jedoch keine Beschreibungen. Die automatisch generierte Hilfe enthält Text, der den Benutzer angibt, das Cmdlet zum Herunterladen der Hilfe für den Befehl aus dem Internet oder einer Dateifreigabe zu verwenden Update-Help . Außerdem empfiehlt es sich, den Onlineparameter des Get-Help Cmdlets zum Abrufen der Onlineversion des Hilfethemas zu verwenden.

Unterstützende aktualisierbare Hilfe

Benutzer von PowerShell 3.0 und höheren Versionen von PowerShell können aktualisierte Hilfedateien für ein Modul aus dem Internet oder aus einer lokalen Dateifreigabe herunterladen und installieren. Mit Update-Help den Cmdlets Save-Help werden die Verwaltungsdetails vom Benutzer ausgeblendet. Benutzer führen das Update-Help Cmdlet aus, und verwenden Sie dann das Get-Help Cmdlet, um die neuesten Hilfedateien für das Modul an der PowerShell-Eingabeaufforderung zu lesen. Benutzer müssen Windows oder PowerShell nicht neu starten.

Benutzer hinter Firewalls und personen ohne Internetzugriff können auch die aktualisierbare Hilfe verwenden. Administratoren mit Internetzugriff verwenden das Save-Help Cmdlet, um die neuesten Hilfedateien in eine Dateifreigabe herunterzuladen und zu installieren. Anschließend verwenden Benutzer den Path-Parameter des Update-Help Cmdlets, um die neuesten Hilfedateien aus der Dateifreigabe abzurufen.

Modulautoren können Hilfedateien im Modul enthalten und aktualisierbare Hilfe verwenden, um die Hilfedateien zu aktualisieren, oder Hilfedateien aus dem Modul weglassen und aktualisierbare Hilfe verwenden, um sie zu installieren und zu aktualisieren.

Weitere Informationen zur aktualisierbaren Hilfe finden Sie unter Unterstützende aktualisierbare Hilfe.

Unterstützen der Onlinehilfe

Benutzer, die keine aktualisierten Hilfedateien auf ihren Computern installieren können, verlassen sich häufig auf die Onlineversion von Modulhilfethemen. Der Parameter "Online " des Get-Help Cmdlets öffnet die Onlineversion eines Cmdlets oder eines Erweiterten Funktionshilfethemas für den Benutzer im Standard-Internetbrowser.

Das Get-Help Cmdlet verwendet den Wert der HelpUri-Eigenschaft des Cmdlets oder der Funktion, um die Onlineversion des Hilfethemas zu finden.

Ab PowerShell 3.0 können Sie Benutzern helfen, die Onlineversion von Cmdlet- und Funktionshilfethemen zu finden, indem Sie das HelpUri-Attribut für die Cmdlet-Klasse oder die HelpUri-Eigenschaft des CmdletBinding-Attributs definieren. Der Wert des Attributs ist der Wert der HelpUri-Eigenschaft des Cmdlets oder der Funktion.

Weitere Informationen finden Sie in der Unterstützenden Onlinehilfe.

Siehe auch

  • Last updated on