Feedback

Skriva hjälp för PowerShell-moduler

  • Artikel
  • 4 minuter för att läsa

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

Det här dokumentet beskriver format och korrekt placering av modulhjälpämnen och föreslår riktlinjer för modulhjälpens innehåll.

Typer av modulhjälp

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

  • Cmdlet-hjälp. Hjälpavsnitten som beskriver cmdlets 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 providerns hjälpschema.

  • Funktionshjälp. Hjälpavsnitten som beskriver funktioner i en modul kan vara XML-filer som använder schemat för kommandohjälp eller kommentarsbaserade hjälpavsnitt i funktionen, eller skript- eller skriptmodulen

  • Skripthjälp. Hjälpavsnitten som beskriver skript i en modul kan vara XML-filer som använder schemat för kommandohjälp eller kommentarsbaserade hjälpavsnitt i skript- eller skriptmodulen.

  • Konceptuellt ("Om") Hjälp. Du kan använda ett konceptuellt hjälpavsnitt ("om") för att beskriva modulen och dess medlemmar och förklara hur medlemmarna kan användas tillsammans för att utföra uppgifter. Konceptuella hjälpavsnitt är textfiler med Unicode-kodning (UTF-8). Filnamnet måste använda about_<name>.help.txt formatet, till exempel about_MyModule.help.txt . Som standard innehåller PowerShell över 100 av dessa konceptuella om hjälpavsnitt, och de är formaterade som i följande exempel.

    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.

Alla schemafiler finns i $PSHOME\Schemas\PSMaml mappen .

Placering av modulhjälp

Get-HelpCmdleten söker efter modulhjälpämnesfiler i språkspecifika underkataloger i modulkatalogen.

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

<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

Anteckning

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

Få modulhjälp

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

Du kan ange modulhjälpavsnitt på olika språk. Cmdleten visar automatiskt hjälpavsnitt för modulen på det språk som anges för den aktuella användaren i objektet Regionala och Get-Help Språkalternativ i Kontrollpanelen. I Windows Vista och senare versioner av Windows söker efter hjälpämnen i språkspecifika underkataloger i modulkatalogen i enlighet med språkstandarder som har upprättats Get-Help för Windows.

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

Om modulen inte innehåller hjälpavsnitt och det inte finns några hjälpämnen för kommandona i modulen på användarens dator, Get-Help visar automatiskt genererad hjälp. Den automatiskt genererade hjälpen innehåller kommandosyntax, parametrar, indata- och utdatatyper, men innehåller inte några beskrivningar. Den automatiskt genererade hjälpen innehåller text som dirigerar användaren att försöka använda cmdleten för att ladda ned hjälp för kommandot från Update-Help Internet eller en filresurs. Vi rekommenderar också att du använder parametern Online för Get-Help cmdleten 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. Update-Help Save-Help Cmdletarna och döljer hanteringsinformationen för användaren. Användarna kör cmdleten och använder sedan cmdleten för att läsa de senaste hjälpfilerna för modulen Update-Help Get-Help i PowerShell-kommandotolken. Användarna behöver inte starta om Windows eller PowerShell.

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

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

Mer information om uppdatabel hjälp finns i Stöd för uppdatabel hjälp.

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älpavsnitten. Parametern Online för cmdleten öppnar onlineversionen av en cmdlet eller ett avancerat funktionshjälpavsnitt för användaren Get-Help i standardwebbläsaren.

Get-HelpCmdleten 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 helpUri-attributet för cmdlet-klassen eller helpUri-egenskapen 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

Skriva en PowerShell-modul

Stöd för uppdateringsbar hjälp

Stöd för onlinehjälp