Skriva hjälp för PowerShell-modulerWriting Help for PowerShell Modules

PowerShell-moduler kan innehålla hjälp avsnitt om modulen och om modul medlemmar, till exempel cmdlets, providrar, funktioner och skript.PowerShell modules can include Help topics about the module and about the module members, such as cmdlets, providers, functions and scripts. Get-HelpCmdleten visar hjälp avsnitten för modulen i samma format som den visar hjälp för andra PowerShell-objekt och användare använder standard Get-Help kommandon för att hämta hjälp avsnitten.The Get-Help cmdlet displays the module Help topics in the same format as it displays Help for other PowerShell items, and users use standard Get-Help commands to get the Help topics.

I det här dokumentet beskrivs formatet och rätt placering av hjälp avsnitt för moduler, och det föreslår rikt linjer för hjälp innehåll i modulen.This document explains the format and correct placement of module Help topics, and it suggests guidelines for module Help content.

Typer av modul-hjälpTypes of Module Help

En modul kan innehålla följande typer av hjälp.A module can include the following types of Help.

  • Cmdlet-hjälp.Cmdlet Help. Hjälp avsnitten som beskriver cmdlets i en modul är XML-filer som använder kommandot hjälp schema för kommandotThe Help topics that describe cmdlets in a module are XML files that use the command help schema

  • Leverantörs hjälp.Provider Help. Hjälp avsnitten som beskriver leverantörer i en modul är XML-filer som använder providerns hjälp schema.The Help topics that describe providers in a module are XML files that use the provider help schema.

  • Funktions hjälp.Function Help. Hjälp avsnitten som beskriver funktioner i en modul kan vara XML-filer som använder kommandot hjälp schema eller kommentarer baserade hjälp avsnitt i funktionen, skript-eller skript-modulenThe Help topics that describe functions in a module can be XML files that use the command help schema or comment-based Help topics within the function, or the script or script module

  • Skript hjälp.Script Help. De hjälp avsnitt som beskriver skript i en modul kan vara XML-filer som använder kommandot hjälp schema eller kommentarer baserade hjälp avsnitt i skript-eller skript-modulen.The Help topics that describe scripts in a module can be XML files that use the command help schema or comment-based Help topics in the script or script module.

  • Konceptuell ("About") hjälp.Conceptual ("About") Help. Du kan använda ett konceptuellt hjälp avsnitt för att beskriva modulen och dess medlemmar och förklara hur medlemmarna kan användas tillsammans för att utföra uppgifter.You can use a conceptual ("about") Help topic to describe the module and its members and to explain how the members can be used together to perform tasks. Konceptuella hjälp ämnen är textfiler med Unicode-kodning (UTF-8).Conceptual Help topics are text files with Unicode (UTF-8) encoding. Fil namnet måste använda about_<name>.help.txt formatet, till exempel about_MyModule.help.txt .The filename must use the about_<name>.help.txt format, such as about_MyModule.help.txt. Som standard innehåller PowerShell över 100 av dessa begrepp om hjälp avsnitt och de formateras som i följande exempel.By default, PowerShell includes over 100 of these conceptual About Help topics, and they are formatted like the following example.

    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.
    
    

Du hittar alla schemafiler i $PSHOME\Schemas\PSMaml mappen.All of the schema files can be found in the $PSHOME\Schemas\PSMaml folder.

Placering av modulens hjälpPlacement of Module Help

Get-HelpCmdleten söker efter modulens hjälp ämnes filer i språkspecifika under kataloger i modulens katalog.The Get-Help cmdlet looks for module Help topic files in language-specific subdirectories of the module directory.

Följande katalog struktur diagram visar till exempel platsen för hjälp avsnitten för SampleModule-modulen.For example, the following directory structure diagram shows the location of the Help topics for the SampleModule module.

<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 exemplet <ModulePath> representerar plats hållaren en av Sök vägarna i PSModulePath miljö variabeln, till exempel $HOME\Documents\Modules , $PSHOME\Modules eller en anpassad sökväg som användaren anger.In the example, the <ModulePath> placeholder represents one of the paths in the PSModulePath environment variable, such as $HOME\Documents\Modules, $PSHOME\Modules, or a custom path that the user specifies.

Hjälp för att hämta modulGetting Module Help

När en användare importerar en modul till en session, importeras hjälp avsnitten för modulen till sessionen tillsammans med modulen.When a user imports a module into a session, the Help topics for that module are imported into the session along with the module. Du kan visa hjälp ämnets filer i värdet för nyckeln FileList i modulen manifest, men hjälp ämnen påverkas inte av Export-ModuleMember cmdleten.You can list the Help topic files in the value of the FileList key in the module manifest, but Help topics are not affected by the Export-ModuleMember cmdlet.

Du kan tillhandahålla hjälp avsnitt för moduler på olika språk.You can provide module Help topics in different languages. Get-HelpCmdleten visar automatiskt hjälp avsnitt för modulen på det språk som har angetts för den aktuella användaren i objektet nationella inställningar och språk inställningar på kontroll panelen.The Get-Help cmdlet automatically displays module Help topics in the language that is specified for the current user in the Regional and Language Options item in Control Panel. I Windows Vista och senare versioner av Windows kan du Get-Help söka efter hjälp avsnitten i språkspecifika under kataloger i modulens katalog i enlighet med de språk reserv standarder som har upprättats för Windows.In Windows Vista and later versions of Windows, Get-Help searches for the Help topics in language-specific subdirectories of the module directory in accordance with the language fallback standards established for Windows.

Från och med PowerShell 3,0 körs ett Get-Help kommando för en cmdlet eller funktion som aktiverar automatisk import av modulen.Beginning in PowerShell 3.0, running a Get-Help command for a cmdlet or function triggers automatic importing of the module. Get-HelpCmdleten visar omedelbart innehållet i hjälp avsnitten i modulen.The Get-Help cmdlet immediately displays the contents of the help topics in the module.

Om modulen inte innehåller hjälp ämnen och det inte finns några hjälp avsnitt för kommandona i modulen på användarens dator, Get-Help visar den automatiskt genererade hjälpen.If the module does not contain help topics and there are no help topics for the commands in the module on the user's computer, Get-Help displays auto-generated help. Den automatiskt genererade hjälpen innehåller kommandosyntaxen, parametrarna och indata-och utdatatyperna, men innehåller inte några beskrivningar.The auto-generated help includes the command syntax, parameters, and input and output types, but does not include any descriptions. Den automatiskt genererade hjälpen innehåller text som instruerar användaren att försöka använda Update-Help cmdleten för att hämta hjälp för kommandot från Internet eller en fil resurs.The auto-generated help includes text that directs the user to try to use the Update-Help cmdlet to download help for the command from the internet or a file share. Det rekommenderar också att du använder Get-Help cmdleten online för att hämta online-versionen av hjälp avsnittet.It also recommends using the Online parameter of the Get-Help cmdlet to get the online version of the help topic.

Stöd för uppdateringsbar hjälpSupporting Updatable Help

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 fil resurs.Users of PowerShell 3.0 and later versions of PowerShell can download and install updated help files for a module from the internet or from a local file share. Update-Help Save-Help Cmdletarna och döljer hanterings detaljerna från användaren.The Update-Help and Save-Help cmdlets hide the management details from the user. Användare kör Update-Help cmdleten och använder sedan Get-Help cmdleten för att läsa de senaste hjälpfilerna för modulen i PowerShell-Kommandotolken.Users run the Update-Help cmdlet and then use the Get-Help cmdlet to read the newest help files for the module at the PowerShell command prompt. Användarna behöver inte starta om Windows eller PowerShell.Users do not need to restart Windows or PowerShell.

Användare bakom brand väggar och sådana utan Internet åtkomst kan också använda uppdaterings bara hjälp.Users behind firewalls and those without internet access can use Updatable Help, as well. Administratörer med Internet åtkomst använder Save-Help cmdleten för att hämta och installera de senaste hjälpfilerna till en fil resurs.Administrators with internet access use the Save-Help cmdlet to download and install the newest help files to a file share. Sedan använder användarna Sök vägs parametern för Update-Help cmdleten för att hämta de senaste hjälpfilerna från fil resursen.Then, users use the Path parameter of the Update-Help cmdlet to get the newest help files from the file share.

Module-författare kan inkludera hjälpfiler i modulen och använda uppdaterings bara hjälp för att uppdatera hjälpfilerna eller utelämna hjälpfiler från modulen och använda uppdaterings bara hjälp både för att installera och uppdatera dem.Module authors can include help files in the module and use Updatable Help to update the help files, or omit help files from the module and use Updatable Help both to install and to update them.

Mer information om uppdaterings bar hjälp finns i support uppdaterings bara hjälp.For more information about Updatable Help, see Supporting Updatable Help.

Stöd för onlinehjälpSupporting Online Help

Användare som inte kan eller inte installerar uppdaterade hjälpfiler på sina datorer förlitar sig ofta på online-versionen av hjälp avsnitten för modulen.Users who cannot or do not install updated help files on their computers often rely on the online version of module help topics. Cmdleten online för Get-Help cmdlet: en öppnar online-versionen av en cmdlet eller ett avancerad funktions hjälp avsnitt för användaren i standard webbläsaren.The Online parameter of the Get-Help cmdlet opens the online version of a cmdlet or advanced function help topic for the user in their default internet browser.

Get-HelpCmdlet: en använder värdet för HelpUri -egenskapen för cmdleten eller funktionen för att hitta online-versionen av hjälp avsnittet.The Get-Help cmdlet uses the value of the HelpUri property of the cmdlet or function to find the online version of the help topic.

Från och med PowerShell 3,0 kan du hjälpa användarna att hitta online-versionen av cmdlet-och Function-hjälp avsnitten genom att definiera attributet HelpUri i cmdlet-klassen eller egenskapen HelpUri för attributet CmdletBinding .Beginning in PowerShell 3.0, you can help users find the online version of cmdlet and function help topics by defining the HelpUri attribute on the cmdlet class or the HelpUri property of the CmdletBinding attribute. Värdet för attributet är värdet för HelpUri -egenskapen för cmdleten eller funktionen.The value of the attribute is the value of the HelpUri property of the cmdlet or function.

Mer information finns i support online-hjälpen.For more information, see Supporting Online Help.

Se ävenSee Also

Skriva en PowerShell-modulWriting a PowerShell Module

Stöd för uppdateringsbar hjälpSupporting Updatable Help

Stöd för onlinehjälpSupporting Online Help