Sdílet prostřednictvím

Podpora Online nápovědy

  • Článek

Poznámka:

Ruční vytváření nápovědy založené na JAZYCE XML je velmi obtížné. Modul PlatyPS umožňuje psát nápovědu v Markdownu a pak ji převést na nápovědu založenou na jazyce XML. To usnadňuje psaní a údržbu nápovědy. PlatyPS vám také můžou vytvořit balíčky aktualizovatelné nápovědy. Další informace naleznete v tématu Vytvoření nápovědy založené na jazyce XML pomocí platyPS.

Počínaje PowerShellem 3.0 existují dva způsoby podpory funkce Get-Help Online pro příkazy PowerShellu. Toto téma vysvětluje, jak tuto funkci implementovat pro různé typy příkazů.

Informace o online nápovědě

Online nápověda byla vždy důležitou součástí PowerShellu. I když rutina Get-Help zobrazuje témata nápovědy na příkazovém řádku, mnoho uživatelů upřednostňuje možnosti čtení online, včetně barevného kódování, hypertextových odkazů a sdílení nápadů v obsahu komunity a dokumentech založených na wikiwebu. Nejdůležitější je, že před nástupem aktualizovatelné nápovědy online poskytla nejvíce up-to-date verze souborů nápovědy.

S nástupem aktualizovatelné nápovědy v PowerShellu 3.0 stále hraje online nápověda zásadní roli. Kromě flexibilního uživatelského prostředí poskytuje online nápověda nápovědu uživatelům, kteří nebudou nebo nemůžou používat aktualizovatelnou nápovědu ke stažení témat nápovědy.

Jak funguje Get-Help -Online

Aby uživatelé mohli najít témata online nápovědy pro příkazy, má příkaz Get-Help parametr Online, který otevře online verzi tématu nápovědy pro příkaz ve výchozím internetovém prohlížeči uživatele.

Například následující příkaz otevře online téma nápovědy pro rutinu Invoke-Command.

Get-Help Invoke-Command -Online

Pokud chcete implementovat Get-Help -Online, rutina Get-Help hledá identifikátor URI (Uniform Resource Identifier) pro téma nápovědy k online verzi v následujících umístěních.

  • První odkaz v části Související odkazy tématu nápovědy pro příkaz. Téma nápovědy musí být nainstalováno na počítači uživatele. Tato funkce byla představena v PowerShellu 2.0.

  • HelpUri vlastnost libovolného příkazu. Vlastnost HelpUri je přístupná i v případě, že téma nápovědy pro příkaz není nainstalované na počítači uživatele. Tato funkce byla představena v PowerShellu 3.0.

    Get-Help hledá identifikátor URI v první položce v části Související odkazy před získáním hodnoty vlastnosti HelpUri. Pokud je hodnota vlastnosti nesprávná nebo se změnila, můžete ji přepsat zadáním jiné hodnoty do prvního souvisejícího odkazu. První související odkaz ale funguje jenom v případě, že jsou témata nápovědy nainstalovaná na počítači uživatele.

Pro libovolný příkaz můžete podporovat Get-Help -Online přidáním platného identifikátoru URI k první položce v souvisejících odkazů části tématu nápovědy založeného na jazyce XML pro tento příkaz. Tato možnost je platná pouze v tématech nápovědy založených na jazyce XML a funguje pouze v případě, že je téma nápovědy nainstalováno na počítači uživatele. Při instalaci tématu nápovědy a naplnění identifikátoru URI má tato hodnota přednost před vlastností HelpUri příkazu.

Chcete-li tuto funkci podporovat, musí se identifikátor URI objevit v elementu maml:uri pod prvním prvkem maml:relatedLinks/maml:navigationLink v elementu maml:relatedLinks.

Následující kód XML ukazuje správné umístění identifikátoru URI. Osvědčeným postupem je Online version: text v elementu maml:linkText, ale nevyžaduje se.

<maml:relatedLinks>
    <maml:navigationLink>
        <maml:linkText>Online version:</maml:linkText>
        <maml:uri>https://go.microsoft.com/fwlink/?LinkID=113279</maml:uri>
    </maml:navigationLink>
    <maml:navigationLink>
        <maml:linkText>about_History</maml:linkText>
        <maml:uri/>
    </maml:navigationLink>
</maml:relatedLinks>

Přidání vlastnosti HelpUri do příkazu

Tato část ukazuje, jak přidat HelpUri vlastnost do příkazů různých typů.

Přidání vlastnosti HelpUri do rutiny

Pro rutiny napsané v jazyce C# přidejte atribut HelpUri do třídy Rutina. Hodnota atributu musí být identifikátor URI, který začíná http nebo https.

Následující kód ukazuje atribut HelpUri třídy rutiny Get-History.

[Cmdlet(VerbsCommon.Get, "History", HelpUri = "https://go.microsoft.com/fwlink/?LinkID=001122")]

Přidání vlastnosti HelpUri do rozšířené funkce

U pokročilých funkcí přidejte do atributu RutinaBinding vlastnost HelpUri. Hodnota vlastnosti musí být identifikátor URI, který začíná řetězcem http nebo https.

Následující kód ukazuje atribut HelpUri funkce New-Calendar.

function New-Calendar {
    [CmdletBinding(SupportsShouldProcess=$true,
    HelpUri="https://go.microsoft.com/fwlink/?LinkID=01122")]

Přidání atributu HelpUri do příkazu cim

Pro příkazy CIM přidejte atribut HelpUri do elementu CmdletMetadata v souboru CDXML. Hodnota atributu musí být identifikátor URI, který začíná http nebo https.

Následující kód ukazuje atribut HelpUri příkazu Start-Debug CIM.

<CmdletMetadata Verb="Debug" HelpUri="https://go.microsoft.com/fwlink/?LinkID=001122"/>

Přidání atributu HelpUri do pracovního postupu

Pro pracovní postupy napsané v jazyce PowerShellu přidejte do kódu pracovního postupu klíčové slovo .EXTERNALHELP komentáře. Hodnota klíčového slova musí být identifikátor URI začínající http nebo https.

Poznámka:

Vlastnost HelpUri není podporována pro pracovní postupy založené na XAML v PowerShellu.

Následující kód ukazuje klíčové slovo .EXTERNALHELP v souboru pracovního postupu.

# .EXTERNALHELP "https://go.microsoft.com/fwlink/?LinkID=138338"