Freigeben über

Schreiben einer Hilfe für PowerShell-Module

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

In diesem Dokument werden das Format und die richtige Platzierung von Modulhilfethemen erläutert, und es werden Richtlinien für den Hilfeinhalt des Moduls vorgeschlagen.

Typen der Modulhilfe

Ein Modul kann die folgenden Hilfetypen enthalten.

  • Cmdlet-Hilfe. Die Hilfethemen, in denen Cmdlets in einem Modul beschrieben werden, sind XML-Dateien, die das Befehlshilfeschema verwenden.

  • Anbieterhilfe. Die Hilfethemen, in denen Anbieter in einem Modul beschrieben werden, sind XML-Dateien, die das Anbieterhilfeschema verwenden.

  • Funktionshilfe. Die Hilfethemen, die Funktionen in einem Modul beschreiben, können XML-Dateien sein, die das Hilfeschema des Befehls 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 Hilfeschema des Befehls oder kommentarbasierte Hilfethemen im Skript- oder Skriptmodul verwenden.

  • Konzeptionelle Hilfe ("About") Sie können ein konzeptionelles Hilfethema ("about") verwenden, um das Modul und seine Elemente zu beschreiben und zu erläutern, wie die Elemente zusammen zum Ausführen von Aufgaben verwendet werden können. Konzeptionelle Hilfethemen sind Textdateien mit Unicode-Codierung (UTF-8). Der Dateiname muss das about_<name>.help.txt Format verwenden, about_MyModule.help.txt z. B. . Standardmäßig enthält PowerShell mehr als 100 dieser konzeptionellen Themen zur Hilfe und ist wie im folgenden Beispiel formatiert.

    TOPIC
    about_<subject or module name>

SHORT DESCRIPTION
    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.

KEYWORDS
    Terms or titles on which you might expect your users to search for the information in this topic.

SEE ALSO
    Text-only references for further reading. Hyperlinks cannot work in the PowerShell console.

Alle Schemadateien befinden sich im $PSHOME\Schemas\PSMaml Ordner .

Platzierung der Modulhilfe

Das Get-Help Cmdlet sucht in sprachspezifischen Unterverzeichnissen des Modulverzeichnisses nach Hilfethemadateien für Module.

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 Umgebungsvariablen dar, z. B. $HOME\Documents\Modules , oder einen $PSHOME\Modules benutzerdefinierten Pfad, den der Benutzer angibt.

Abrufen der Modulhilfe

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 Export-ModuleMember betroffen.

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

Ab PowerShell 3.0 löst das Ausführen eines Befehls für ein Cmdlet oder eine Funktion den Get-Help 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 zeigt automatisch generierte Hilfe an. Die automatisch generierte Hilfe enthält die Befehlssyntax, Parameter sowie Eingabe- und Ausgabetypen, enthält jedoch keine Beschreibungen. Die automatisch generierte Hilfe enthält Text, der den Benutzer anleitet, das Update-Help Cmdlet zum Herunterladen der Hilfe für den Befehl aus dem Internet oder einer Dateifreigabe zu verwenden. Außerdem wird empfohlen, den Onlineparameter des Get-Help Cmdlets zu verwenden, um die Onlineversion des Hilfethemas abzurufen.

Unterstützung einer aktualisierbaren Hilfe

Benutzer von PowerShell 3.0 und höher können aktualisierte Hilfedateien für ein Modul aus dem Internet oder einer lokalen Dateifreigabe herunterladen und installieren. Die Update-Help Save-Help Cmdlets und blenden die Verwaltungsdetails für den Benutzer aus. Benutzer führen das Cmdlet aus Update-Help und verwenden 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 Benutzer ohne Internetzugriff können auch aktualisierbare Hilfe verwenden. Administratoren mit Internetzugriff verwenden das Save-Help Cmdlet , um die neuesten Hilfedateien herunterzuladen und auf einer Dateifreigabe 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 in das Modul einschließen und die aktualisierbare Hilfe verwenden, um die Hilfedateien zu aktualisieren, oder Hilfedateien aus dem Modul weglassen und die aktualisierbare Hilfe verwenden, um sie zu installieren und zu aktualisieren.

Weitere Informationen zur aktualisierbaren Hilfe finden Sie unter Supporting Updatable Help.

Unterstützung einer Onlinehilfe

Benutzer, die aktualisierte Hilfedateien auf ihren Computern nicht installieren können oder nicht, verlassen sich häufig auf die Onlineversion von Modulhilfethemen. Der Online-Parameter des Get-Help Cmdlets öffnet die Onlineversion eines Cmdlets oder eines Hilfethemas für erweiterte Funktionen für den Benutzer in dessen Standardinternetbrowser.

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 unter Unterstützen der Onlinehilfe.

Weitere Informationen

Schreiben eines PowerShell-Moduls

Unterstützung einer aktualisierbaren Hilfe

Unterstützung einer Onlinehilfe