Stöd för onlinehjälp

Anmärkning

Manuell redigering av XML-baserad hjälp är mycket svårt. Med modulen PlatyPS kan du skriva hjälp i Markdown och sedan konvertera den till XML-baserad hjälp. Detta gör det mycket enklare att skriva och underhålla hjälp. PlatyPS kan också skapa uppdateringsbara hjälppaket åt dig. Mer information finns i Skapa XML-baserad hjälp med PlatyPS.

Från och med PowerShell 3.0 finns det två sätt att stödja funktionen Get-Help Online för PowerShell-kommandon. I det här avsnittet beskrivs hur du implementerar den här funktionen för olika kommandotyper.

Om onlinehjälp

Onlinehjälp har alltid varit en viktig del av PowerShell. Även om cmdleten Get-Help visar hjälpämnen i kommandotolken föredrar många användare upplevelsen av att läsa online, inklusive färgkodning, hyperlänkar och delningsidéer i communityinnehåll och wiki-baserade dokument. Det viktigaste är att onlinehjälpen före tillkomsten av updatable-hjälpen gav den mest up-to-date-versionen av hjälpfilerna.

Med tillkomsten av Updatable Help i PowerShell 3.0 spelar onlinehjälp fortfarande en viktig roll. Förutom den flexibla användarupplevelsen ger onlinehjälpen hjälp till användare som inte kan eller inte kan använda updatable-hjälp för att ladda ned hjälpavsnitt.

Så här fungerar Get-Help -Online

För att hjälpa användarna att hitta onlinehjälpavsnitten för kommandon har kommandot Get-Help en Online-parameter som öppnar onlineversionen av hjälpavsnittet för ett kommando i användarens standardwebbläsare.

Följande kommando öppnar till exempel onlinehjälpavsnittet för cmdleten Invoke-Command.

Get-Help Invoke-Command -Online

För att implementera Get-Help -Onlineletar Get-Help-cmdleten efter en URI (Uniform Resource Identifier) för onlineversionens hjälpavsnitt på följande platser.

• Den första länken i avsnittet Relaterade länkar i hjälpavsnittet för kommandot. Hjälpavsnittet måste vara installerat på användarens dator. Den här funktionen introducerades i PowerShell 2.0.

• Egenskapen HelpUri för alla kommandon. Egenskapen HelpUri är tillgänglig även när hjälpavsnittet för kommandot inte är installerat på användarens dator. Den här funktionen introducerades i PowerShell 3.0.

  Get-Help söker efter en URI i den första posten i avsnittet Relaterade länkar innan du får egenskapsvärdet HelpUri. Om egenskapsvärdet är felaktigt eller har ändrats kan du åsidosätta det genom att ange ett annat värde i den första relaterade länken. Den första relaterade länken fungerar dock bara när hjälpavsnitten är installerade på användarens dator.

Lägga till en URI i den första relaterade länken i ett kommandohjälpavsnitt

Du kan stödja Get-Help -Online för valfritt kommando genom att lägga till en giltig URI i den första posten i avsnittet Relaterade länkar i det XML-baserade hjälpavsnittet för kommandot. Det här alternativet är endast giltigt i XML-baserade hjälpavsnitt och fungerar bara när hjälpavsnittet är installerat på användarens dator. När hjälpavsnittet har installerats och URI:n har fyllts i har det här värdet företräde framför HelpUri--egenskapen för kommandot.

För att stödja den här funktionen måste URI:n visas i elementet maml:uri under det första maml:relatedLinks/maml:navigationLink elementet i maml:relatedLinks-elementet.

Följande XML visar rätt placering av URI:n. Den Online version: texten i elementet maml:linkText är en bra idé, men den krävs inte.

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

Lägga till egenskapen HelpUri i ett kommando

Det här avsnittet visar hur du lägger till egenskapen HelpUri till kommandon av olika typer.

Lägga till en HelpUri-egenskap i en cmdlet

För cmdletar som skrivits i C#lägger du till ett HelpUri--attribut i klassen Cmdlet. Värdet för attributet måste vara en URI som börjar med http eller https.

Följande kod visar attributet HelpUri för cmdlet-klassen Get-History.

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

Lägga till en HelpUri-egenskap i en avancerad funktion

För avancerade funktioner lägger du till egenskapen HelpUri i attributet CmdletBinding. Värdet för egenskapen måste vara en URI som börjar med "http" eller "https".

Följande kod visar attributet HelpUri för funktionen New-Calendar

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

Lägga till ett HelpUri-attribut till ett cim-kommando

För CIM-kommandon lägger du till ett HelpUri--attribut till CmdletMetadata--elementet i CDXML-filen. Värdet för attributet måste vara en URI som börjar med http eller https.

Följande kod visar attributet HelpUri för kommandot Start-Debug CIM

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

Lägga till ett HelpUri-attribut i ett arbetsflöde

För arbetsflöden som är skrivna på PowerShell-språket lägger du till ett nyckelord för .EXTERNALHELP kommentar i arbetsflödeskoden. Värdet för nyckelordet måste vara en URI som börjar med http eller https.

Anmärkning

Egenskapen HelpUri stöds inte för XAML-baserade arbetsflöden i PowerShell.

Följande kod visar nyckelordet .EXTERNALHELP i en arbetsflödesfil.

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