Konvertera och publicera hjälpfilerna

Vid det här laget bör du ha skapat, redigerat och testat Markdown-hjälpfilerna. Nästa steg är att konvertera Markdown-källfilerna till MAML-hjälpfiler och publicera för modulen.

Konvertera Markdown-filerna till MAML

I följande exempel importeras Markdown-hjälpfilerna i katalogen .\WidgetModule och sedan exporteras kommandot help till MAML-format i katalogen .\maml .

Measure-PlatyPSMarkdown -Path .\WidgetModule\*.md |
    Where-Object Filetype -match 'CommandHelp' |
    Import-MarkdownCommandHelp -Path {$_.FilePath} |
    Export-MamlCommandHelp -OutputFolder .\maml

Publicera hjälpfilerna

Det finns två publiceringsalternativ:

• Inkludera hjälpfilerna i modulen
• Paketera hjälpfilerna för uppdateringsbar hjälp

Alternativ 1: Inkludera hjälpfilerna i modulen

Cmdleten Get-Help söker efter modulen Hjälpämnesfiler i språkspecifika underkataloger i modulkatalogen. Kopiera MAML-hjälpfilerna och alla about_*.help.txt filer till en språkspecifik mapp i modulkatalogen. Mappnamnet måste använda kulturkodformatet, till exempel en-US. Följande katalogstrukturdiagram visar till exempel platsen för hjälpavsnitten för WidgetModule-modulen.

<PSModulePath>/
└── WidgetModule/
    └── en-US/
        ├── about_WidgetModule.help.txt
        ├── WidgetModule-Help.xml
        └── NestedWidgetModule.dll-Help.xml

Om du har skapat hjälp på andra språk skapar du ytterligare mappar för varje språk.

Alternativ 2: Paketera hjälpfilerna för uppdateringsbar hjälp

För att stödja uppdateringsbar hjälp måste du paketera hjälpfilen (både MAML och textbaserad hjälp) i en arkivfil och skapa en HelpInfo.xml fil som innehåller nedladdningsplatsen för hjälpinnehållet, versionen av hjälpen och de språk som är tillgängliga.

Du måste också vara värd för hjälpinnehållet på en webbserver som stöder HTTPS. Modulen måste ha ett modulmanifest. Egenskapen HelpInfoUri i manifestet måste innehålla URL:en till mappplatsen på webbservern där HelpInfo.xml filen finns. Den här URL:en ska vara mappens plats, inte den fullständiga sökvägen till HelpInfo.xml filen, och den måste sluta med ett snedstreck (/).

Mer information finns i Redigering av uppdateringsbar hjälp.

PlatyPS gör denna process enklare. Om modulmanifestet innehåller egenskapen HelpInfoUri när du skapar modulens Markdown-fil lägger PlatyPS automatiskt till nödvändiga metadata i Markdown-filen. Använd följande exempel för att skapa det uppdateringsbara hjälppaketet.

$params = @{
    CabinetFilesFolder = '.\maml\WidgetModule'
    MarkdownModuleFile = '.\WidgetModule\WidgetModule.md'
    OutputFolder       = '.\helppackage'
}
New-HelpCabinetFile @params

Parametern CabinetFilesFolder anger den mapp som innehåller MAML- och textbaserade hjälpfiler som ska ingå i paketet. Parametern MarkdownModuleFile anger Markdown-modulfilen som innehåller de metadata som krävs för att skapa HelpInfo.xml filen. Parametern OutputFolder anger mappen där .cab filerna .zip och HelpInfo.xml filen skapas. Kopiera dessa filer till webbservern på den plats som anges av egenskapen HelpInfoUri .

Egenskapen HelpInfoUri i manifestet måste innehålla URL:en till mappplatsen på webbservern där HelpInfo.xml filen finns. Cmdleten Update-Help använder den här platsen för att skapa den fullständiga sökvägen till HelpInfo.xml filen. Cmdleten Update-Help använder informationen i HelpInfo.xml filen för att skapa den fullständiga sökvägen till hjälpinnehållsfilerna.

Mer information finns i Så här fungerar uppdateringsbar hjälp.