Dela via

Skriva hjälp för PowerShell-moduler

PowerShell-moduler kan innehålla hjälpavsnitt om modulen och om modulmedlemmar, till exempel cmdletar, leverantörer, funktioner och skript. Cmdleten Get-Help visar modulens hjälpavsnitt i samma format som den visar Hjälp för andra PowerShell-objekt, och användarna använder standardkommandon Get-Help för att hämta hjälpavsnitten.

Det här dokumentet beskriver formatet och rätt placering av modulhjälpavsnitten och föreslår riktlinjer för modulhjälpinnehåll.

Hjälp om typer av moduler

En modul kan innehålla följande typer av hjälp.

  • XML-baserad hjälp

    • Cmdlet-hjälp. Hjälpavsnitten som beskriver cmdletar i en modul är XML-filer som använder kommandohjälpschemat
    • Providerhjälp. Hjälpavsnitten som beskriver providers i en modul är XML-filer som använder providerhjälpschemat.
    • Funktionshjälp. Hjälpavsnitten som beskriver funktioner i en modul kan vara XML-filer som använder kommandohjälpschemat eller kommentarsbaserade hjälpavsnitt i funktionen, eller skript- eller skriptmodulen
    • Hjälp om skript. Hjälpavsnitten som beskriver skript i en modul kan vara XML-filer som använder kommandohjälpsschemat eller kommentarsbaserade hjälpavsnitt i skript- eller skriptmodulen.
    • Mappen $PSHOME\Schemas\PSMaml innehåller schemafilerna som definierar XML-formatet.

  • Konceptuella ("Om") hjälptextfiler

    Du kan använda ett konceptuellt ("om") hjälpavsnitt för att beskriva modulen och dess medlemmar och förklara hur medlemmarna kan användas tillsammans för att utföra uppgifter. Som standard innehåller PowerShell över 100 av dessa konceptuella om hjälpavsnitt. Filnamnet måste använda about_<name>.help.txt formatet, till exempel about_MyModule.help.txt.

    Anmärkning

    Avsnittsrubriken TOPIC måste starta i den första kolumnen på den första raden i filen. Avsnittsinnehållet på den andra raden ska matcha filnamnet, utan suffixet .help.txt . Du måste dra in innehållet exakt 4 blanksteg. Den tredje raden måste vara tom. Avsnittsrubriken SYNOPSIS måste starta i den första kolumnen på den fjärde raden. Du måste dra in innehållet på den femte raden med exakt 4 blanksteg. Dessa krav är nödvändiga för att cmdleten Get-Help ska känna igen innehållet korrekt.

    TOPIC
    about_<subject or module name>

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

    Du kan använda följande exempelmall som utgångspunkt för att skriva konceptuella hjälpavsnitt. Förutom de två första avsnitten är strukturen för konceptuell hjälpavsnitt godtycklig. De återstående avsnittsrubrikerna kan vara vad som är lämpligt för ditt innehåll.

    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.

    Du kan använda valfri stil och markering, men PowerShell ser det som oformaterad text och det finns ingen särskild återgivning av texten i PowerShell-konsolen. Följande förslag säkerställer bästa möjliga visningsresultat och läsbarhet.

    • Använd UTF-8 med BOM-kodning för att se till att alla specialtecken (flera byte) visas korrekt.
    • Stryk under avsnittsrubriker eller använd alla versaler för att få dem att sticka ut. Det gör innehållet enklare att skanna.
    • Begränsa längden på varje rad till 80 tecken.
    • Dra in kodblock och exempelutdata för att skilja dem från den omgivande prosa.

Placering av modulhjälp

Cmdleten Get-Help söker efter modulen Hjälpämnesfiler i språkspecifika underkataloger i modulkatalogen.

Följande katalogstrukturdiagram visar till exempel platsen för hjälpavsnitten för SampleModule-modulen.

<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

Anmärkning

I exemplet <ModulePath> representerar platshållaren en av sökvägarna i PSModulePath miljövariabeln, till exempel $HOME\Documents\Modules, $PSHOME\Moduleseller en anpassad sökväg som användaren anger.

Få modulhjälp

När en användare importerar en modul till en session importeras hjälpavsnitten för modulen till sessionen tillsammans med modulen. Du kan lista hjälpavsnittsfilerna i värdet för filelist-nyckeln i modulmanifestet, men hjälpavsnitten påverkas inte av cmdleten Export-ModuleMember .

Du kan ange modulhjälpavsnitt på olika språk. Cmdleten Get-Help visar automatiskt modulhjälpavsnitt på det språk som har angetts för den aktuella användaren i objektet Nationella alternativ och Språkalternativ på Kontrollpanelen. I Windows Vista och senare versioner av Windows Get-Help söker du efter hjälpavsnitten i språkspecifika underkataloger i modulkatalogen i enlighet med de standarder för språkåterställning som fastställts för Windows.

Från och med PowerShell 3.0 utlöser körning av ett Get-Help kommando för en cmdlet eller funktion automatisk import av modulen. Cmdleten Get-Help visar omedelbart innehållet i hjälpavsnitten i modulen.

Om modulen inte innehåller hjälpavsnitt och det inte finns några hjälpavsnitt för kommandona i modulen på användarens dator Get-Help , visas automatiskt genererad hjälp. Den automatiskt genererade hjälpen innehåller kommandosyntaxen, parametrarna och indata- och utdatatyperna, men innehåller inga beskrivningar. Den automatiskt genererade hjälpen innehåller text som instruerar användaren att försöka använda cmdleten Update-Help för att hämta hjälp för kommandot från Internet eller en filresurs. Den rekommenderar också att du använder onlineparametern för cmdleten Get-Help för att hämta onlineversionen av hjälpavsnittet.

Stöd för uppdateringsbar hjälp

Användare av PowerShell 3.0 och senare versioner av PowerShell kan ladda ned och installera uppdaterade hjälpfiler för en modul från Internet eller från en lokal filresurs. Cmdletarna Update-Help och Save-Help döljer hanteringsinformationen från användaren. Användarna kör cmdleten Update-Help och använder sedan cmdleten Get-Help för att läsa de senaste hjälpfilerna för modulen i PowerShell-kommandotolken. Användarna behöver inte starta om Windows eller PowerShell.

Användare bakom brandväggar och de som saknar internetåtkomst kan också använda uppdaterbar hjälp. Administratörer med internetåtkomst använder cmdleten Save-Help för att ladda ned och installera de senaste hjälpfilerna till en filresurs. Sedan använder användarna parametern Sökväg för cmdleten Update-Help för att hämta de senaste hjälpfilerna från filresursen.

Modulförfattare kan inkludera hjälpfiler i modulen och använda Updatable Help för att uppdatera hjälpfilerna, eller utelämna hjälpfiler från modulen och använda Updatable Help både för att installera och uppdatera dem.

Mer information om uppdaterad hjälp finns i Support updatable Help.

Stöd för onlinehjälp

Användare som inte kan eller inte installerar uppdaterade hjälpfiler på sina datorer förlitar sig ofta på onlineversionen av modulhjälpämnen. Parametern Online för cmdleten Get-Help öppnar onlineversionen av en cmdlet eller ett avancerat funktionshjälpavsnitt för användaren i deras standardwebbläsare.

Cmdleten Get-Help använder värdet för egenskapen HelpUri för cmdleten eller funktionen för att hitta onlineversionen av hjälpavsnittet.

Från och med PowerShell 3.0 kan du hjälpa användarna att hitta onlineversionen av cmdlet- och funktionshjälpavsnitten genom att definiera attributet HelpUri för cmdlet-klassen eller egenskapen HelpUri för attributet CmdletBinding . Värdet för attributet är värdet för egenskapen HelpUri för cmdleten eller funktionen.

Mer information finns i Stöd för onlinehjälp.

Se även