Ondersteunende online help

Vanaf PowerShell 3.0 zijn er twee manieren om de functie Get-Help Online voor PowerShell-opdrachten te ondersteunen. In dit onderwerp wordt uitgelegd hoe u deze functie implementeert voor verschillende opdrachttypen.

Informatie over Online Help

Online-help is altijd een essentieel onderdeel van PowerShell geweest. Hoewel de Get-Help cmdlet Help-onderwerpen weergeeft bij de opdrachtprompt, geven veel gebruikers de voorkeur aan online lezen, waaronder kleurcodering, hyperlinks en het delen van ideeën in community-inhoud en wikidocumenten. Het belangrijkste is dat voor de komst van Help-informatie die kan worden bijgewerkt, online help de meest up-to-datumversie van de Help-bestanden heeft geleverd.

Met de komst van Updatable Help in PowerShell 3.0 speelt online help nog steeds een belangrijke rol. Naast de flexibele gebruikerservaring biedt online help aan gebruikers die geen of geen updatable Help kunnen gebruiken om Help-onderwerpen te downloaden.

Hoe Get-Help -Online werkt

Om gebruikers te helpen de online-Help-onderwerpen voor opdrachten te vinden, heeft de opdracht Get-Help een onlineparameter waarmee de onlineversie van het Help-onderwerp wordt geopend voor een opdracht in de standaard internetbrowser van de gebruiker.

Met de volgende opdracht wordt bijvoorbeeld het online-Help-onderwerp voor de Invoke-Command-cmdlet geopend.

Get-Help Invoke-Command -Online

Als u Get-Help -Onlinewilt implementeren, zoekt de Get-Help-cmdlet naar een URI (Uniform Resource Identifier) voor het Help-onderwerp voor onlineversies op de volgende locaties.

• De eerste koppeling in de sectie gerelateerde koppelingen van het Help-onderwerp voor de opdracht. Het Help-onderwerp moet worden geïnstalleerd op de computer van de gebruiker. Deze functie is geïntroduceerd in PowerShell 2.0.

• De eigenschap HelpUri van een opdracht. De eigenschap HelpUri is toegankelijk, zelfs wanneer het Help-onderwerp voor de opdracht niet op de computer van de gebruiker is geïnstalleerd. Deze functie is geïntroduceerd in PowerShell 3.0.

  Get-Help zoekt naar een URI in de eerste vermelding in de sectie Gerelateerde koppelingen voordat u de HelpUri eigenschapswaarde ophaalt. Als de eigenschapswaarde onjuist is of is gewijzigd, kunt u deze overschrijven door een andere waarde in te voeren in de eerste gerelateerde koppeling. De eerste gerelateerde koppeling werkt echter alleen wanneer de Help-onderwerpen op de computer van de gebruiker zijn geïnstalleerd.

Een URI toevoegen aan de eerste gerelateerde koppeling van een Help-onderwerp voor opdrachten

U kunt Get-Help -Online voor elke opdracht ondersteunen door een geldige URI toe te voegen aan het eerste item in de sectie Gerelateerde koppelingen van het op XML gebaseerde Help-onderwerp voor de opdracht. Deze optie is alleen geldig in helponderwerpen op basis van XML en werkt alleen wanneer het Help-onderwerp is geïnstalleerd op de computer van de gebruiker. Wanneer het Help-onderwerp is geïnstalleerd en de URI is ingevuld, heeft deze waarde voorrang op de eigenschap HelpUri van de opdracht.

Ter ondersteuning van deze functie moet de URI worden weergegeven in het maml:uri element onder het eerste maml:relatedLinks/maml:navigationLink element in het maml:relatedLinks element.

In de volgende XML ziet u de juiste plaatsing van de URI. De Online version: tekst in het element maml:linkText is een best practice, maar dit is niet vereist.

<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>

De eigenschap HelpUri toevoegen aan een opdracht

In deze sectie ziet u hoe u de eigenschap HelpUri toevoegt aan opdrachten van verschillende typen.

Een HelpUri-eigenschap toevoegen aan een cmdlet

Voeg voor cmdlets die zijn geschreven in C# een HelpUri-kenmerk toe aan de Cmdlet--klasse. De waarde van het kenmerk moet een URI zijn die begint met http of https.

De volgende code toont het kenmerk HelpUri van de cmdlet-klasse Get-History.

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

Een HelpUri-eigenschap toevoegen aan een geavanceerde functie

Voor geavanceerde functies voegt u een eigenschap HelpUri toe aan het kenmerk CmdletBinding. De waarde van de eigenschap moet een URI zijn die begint met http of https.

De volgende code toont het kenmerk HelpUri van de functie New-Calendar

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

Een HelpUri-kenmerk toevoegen aan een cim-opdracht

Voeg voor CIM-opdrachten een HelpUri-kenmerk toe aan het element CmdletMetadata in het CDXML-bestand. De waarde van het kenmerk moet een URI zijn die begint met http of https.

De volgende code toont het HelpUri-kenmerk van de Start-Debug CIM-opdracht

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

Een HelpUri-kenmerk toevoegen aan een werkstroom

Voeg voor werkstromen die zijn geschreven in de PowerShell-taal een .EXTERNALHELP trefwoord voor opmerkingen toe aan de werkstroomcode. De waarde van het trefwoord moet een URI zijn die begint met http of https.

De volgende code toont het .EXTERNALHELP trefwoord in een werkstroombestand.

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