Psaní nápovědy pro moduly PowerShellu

Moduly PowerShellu můžou obsahovat témata nápovědy k modulu a členy modulu, jako jsou rutiny, poskytovatelé, funkce a skripty. Rutina Get-Help zobrazí témata nápovědy modulu ve stejném formátu jako nápověda pro ostatní položky PowerShellu a uživatelé k získání témat nápovědy používají standardní Get-Help příkazy.

Tento dokument vysvětluje formát a správné umístění témat nápovědy modulu a navrhuje pokyny pro obsah nápovědy modulu.

Typy nápovědy k modulu

Modul může obsahovat následující typy nápovědy.

Nápověda založená na JAZYCE XML
- Nápověda k rutině Témata nápovědy popisují rutiny v modulu jsou soubory XML, které používají schéma nápovědy k příkazu.
- Nápověda k poskytovateli Témata nápovědy popisují zprostředkovatele v modulu soubory XML, které používají schéma nápovědy zprostředkovatele.
- Nápověda k funkcím Témata nápovědy, která popisují funkce v modulu, můžou být soubory XML, které používají schéma nápovědy příkazu nebo témata nápovědy založená na komentářích v rámci funkce, nebo skript nebo modul skriptu.
- Nápověda pro skripty Témata nápovědy popisované skripty v modulu můžou být soubory XML, které používají schéma nápovědy příkazu nebo témata nápovědy založená na komentářích v modulu skriptu nebo skriptu.
- Složka $PSHOME\Schemas\PSMaml obsahuje soubory schématu, které definují formát XML.
Koncepční ("O") textové soubory nápovědy

Pomocí konceptuálního tématu nápovědy ("o") můžete popsat modul a jeho členy a vysvětlit, jak se můžou členové společně používat k provádění úkolů. PowerShell ve výchozím nastavení obsahuje více než 100 těchto koncepčních témat nápovědy. Název souboru musí používat about_<name>.help.txt formát, například about_MyModule.help.txt.

Poznámka:

Záhlaví TOPIC oddílu musí začínat prvním sloupcem prvního řádku souboru. Obsah oddílu na druhém řádku by měl odpovídat názvu souboru bez přípony .help.txt . Obsah musíte odsadit přesně o 4 mezery. Třetí řádek musí být prázdný. Záhlaví SYNOPSIS oddílu musí začínat prvním sloupcem čtvrtého řádku. Obsah na pátém řádku musíte odsadit přesně o 4 mezery. Tyto požadavky jsou nezbytné, Get-Help aby rutina správně rozpoznala obsah.
```
TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.
```
Jako výchozí bod pro psaní koncepčních témat nápovědy můžete použít následující ukázkovou šablonu. S výjimkou prvních dvou částí je struktura konceptuálních témat nápovědy libovolná. Zbývající názvy oddílů můžou být vhodné pro váš obsah.
```
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.
```
Můžete použít libovolný styl a značky, ale PowerShell ho vidí jako prostý text a v konzole PowerShellu není žádné speciální vykreslení textu. Následující návrhy zajišťují nejlepší výsledky zobrazení a čitelnost.
- Pomocí kódování UTF-8 můžete zajistit správné zobrazení všech speciálních (vícebajtů) znaků.
- Podtržení záhlaví oddílů nebo použití všech velkých písmen k tomu, aby vynikly. Díky tomu se obsah snadněji prohledává.
- Omezte délku každého řádku na 80 znaků.
- Odsaďte bloky kódu a ukázkový výstup, abyste je oddělili od okolních prose.

Umístění nápovědy k modulu

Rutina Get-Help hledá soubory témat nápovědy modulu v podadresářích adresáře modulu pro konkrétní jazyk.

Například následující diagram struktury adresářů znázorňuje umístění témat nápovědy pro modul 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

Poznámka:

V příkladu <ModulePath> zástupný symbol představuje jednu z cest v PSModulePath proměnné prostředí, například $HOME\Documents\Modules, $PSHOME\Modulesnebo vlastní cestu, kterou uživatel určuje.

Získání nápovědy k modulu

Když uživatel naimportuje modul do relace, témata nápovědy pro tento modul se naimportují do relace spolu s modulem. Soubory témat nápovědy můžete zobrazit v hodnotě klíče FileList v manifestu modulu, ale témata nápovědy nejsou touto rutinou Export-ModuleMember ovlivněna.

Témata nápovědy k modulu můžete poskytnout v různých jazycích. Rutina Get-Help automaticky zobrazí témata nápovědy modulu v jazyce určeném pro aktuálního uživatele v ovládacích panelech místní a jazykové možnosti. Ve Windows Vista a novějších verzích systému Windows Get-Help vyhledá témata nápovědy v podadresářích adresáře modulu pro konkrétní jazyk v souladu se standardy pro použití náhradní verze jazyka stanovené pro Systém Windows.

Počínaje PowerShellem 3.0 se spuštěním příkazu pro rutinu Get-Help nebo funkci aktivuje automatický import modulu. Rutina Get-Help okamžitě zobrazí obsah témat nápovědy v modulu.

Pokud modul neobsahuje témata nápovědy a nejsou k dispozici žádná témata nápovědy pro příkazy v modulu na počítači uživatele, Get-Help zobrazí automaticky vygenerovanou nápovědu. Automaticky generovaná nápověda zahrnuje syntaxi příkazů, parametry a vstupní a výstupní typy, ale neobsahuje žádné popisy. Automaticky generovaná nápověda obsahuje text, který uživatele přesměruje, aby se pokusil pomocí Update-Help rutiny stáhnout nápovědu pro příkaz z internetu nebo sdílené složky. K získání online verze tématu nápovědy se také doporučuje použít parametr Get-Help rutiny.

Podpora aktualizovatelné nápovědy

Uživatelé PowerShellu 3.0 a novějších verzí PowerShellu můžou stahovat a instalovat aktualizované soubory nápovědy pro modul z internetu nebo z místní sdílené složky. Tyto Update-Help rutiny Save-Help skryjí podrobnosti správy od uživatele. Uživatelé tuto rutinu Update-Help spustí a pak pomocí Get-Help této rutiny načtou nejnovější soubory nápovědy pro modul na příkazovém řádku PowerShellu. Uživatelé nemusí restartovat Windows ani PowerShell.

Uživatelé za branami firewall a těmi, kteří nemají přístup k internetu, můžou používat také aktualizovatelnou nápovědu. Správci s přístupem k internetu používají rutinu Save-Help ke stažení a instalaci nejnovějších souborů nápovědy do sdílené složky. Uživatelé pak pomocí parametru Update-Help rutiny získají nejnovější soubory nápovědy ze sdílené složky.

Autoři modulů můžou do modulu zahrnout soubory nápovědy a pomocí aktualizovatelné nápovědy aktualizovat soubory nápovědy nebo vynechat soubory nápovědy z modulu a pomocí aktualizovatelné nápovědy je nainstalovat i aktualizovat.

Další informace o aktualizovatelné nápovědě naleznete v tématu Podpora aktualizovatelné nápovědy.

Podpora online nápovědy

Uživatelé, kteří nemůžou nebo nenainstalují aktualizované soubory nápovědy do svých počítačů, se často spoléhají na online verzi témat nápovědy k modulu. Parametr Online rutiny Get-Help otevře online verzi tématu nápovědy k rutině nebo rozšířené funkci pro uživatele ve výchozím internetovém prohlížeči.

Rutina Get-Help používá hodnotu vlastnosti HelpUri rutiny nebo funkce k vyhledání online verze tématu nápovědy.

Od PowerShellu 3.0 můžete uživatelům pomoct najít online verzi témat nápovědy rutiny a funkce definováním atributu HelpUri třídy rutiny nebo vlastnosti HelpUri atributu CmdletBinding . Hodnota atributu je hodnota vlastnosti HelpUri rutiny nebo funkce.

Další informace najdete v tématu Podpora online nápovědy.

Viz také

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-02