Tworzenie pomocy opartej na formacie XML przy użyciu platformy PlatyPS

Artykuł
11/10/2023

Podczas tworzenia modułu programu PowerShell zawsze zaleca się dołączenie szczegółowej pomocy dla tworzonych poleceń cmdlet. Jeśli polecenia cmdlet są implementowane w skompilowanym kodzie, należy użyć pomocy opartej na języku XML. Ten format XML jest znany jako Microsoft Assistance Markup Language (MAML).

Starsza dokumentacja zestawu POWERShell SDK zawiera szczegółowe informacje dotyczące tworzenia pomocy dla poleceń cmdlet programu PowerShell spakowanych w moduły. Jednak program PowerShell nie udostępnia żadnych narzędzi do tworzenia pomocy opartej na formacie XML. Dokumentacja zestawu SDK wyjaśnia strukturę pomocy MAML, ale pozostawia zadanie tworzenia złożonej i głęboko zagnieżdżonej zawartości MAML ręcznie.

Jest to miejsce, w którym moduł PlatyPS może pomóc.

Co to jest PlatyPS?

PlatyPS to narzędzie typu open source , które zaczęło się jako projekt hackathon , aby ułatwić tworzenie i konserwację mamL. Platforma PlatyPS dokumentuje składnię zestawów parametrów i poszczególne parametry dla każdego polecenia cmdlet w module. Platforma PlatyPS tworzy ustrukturyzowane pliki markdown zawierające informacje o składni. Nie może tworzyć opisów ani udostępniać przykładów.

Platforma PlatyPS tworzy symbole zastępcze, aby wypełnić opisy i przykłady. Po dodaniu wymaganych informacji platyPS kompiluje pliki Markdown do plików MAML. System pomocy programu PowerShell umożliwia również pliki pomocy koncepcyjnej w postaci zwykłego tekstu (informacje o tematach). Platforma PlatyPS ma polecenie cmdlet do utworzenia ustrukturyzowanego szablonu języka Markdown dla nowego pliku o pliku, ale te about_*.help.txt pliki muszą być obsługiwane ręcznie.

Możesz dołączyć pliki pomocy MAML i Text do modułu. Można również użyć platformy PlatyPS, aby skompilować pliki pomocy w pakiecie CAB, który może być hostowany w celu uzyskania pomocy z możliwością aktualizacji.

Rozpoczynanie pracy z platformą PlatyPS

Najpierw należy zainstalować platformę PlatyPS z Galeria programu PowerShell.

# Install using PowerShellGet 2.x
Install-Module platyps -Force

# Install using PSResourceGet 1.x
Install-PSResource platyps -Force

Po zainstalowaniu platformy PlatyPS zaimportuj moduł do sesji.

Import-Module platyps

Poniższy schemat blokowy przedstawia proces tworzenia lub aktualizowania zawartości referencyjnej programu PowerShell.

Przepływ pracy tworzenia pomocy opartej na formacie XML przy użyciu platformy PlatyPS

Tworzenie zawartości języka Markdown dla modułu programu PowerShell

Zaimportuj nowy moduł do sesji. Powtórz ten krok dla każdego modułu, który należy udokumentować.

Uruchom następujące polecenie, aby zaimportować moduły:
```
Import-Module <your module name>
```
Użyj platformy PlatyPS, aby wygenerować pliki Markdown dla strony modułu i wszystkie skojarzone polecenia cmdlet w module. Powtórz ten krok dla każdego modułu, który należy udokumentować.
```
$OutputFolder = <output path>
$parameters = @{
    Module = <ModuleName>
    OutputFolder = $OutputFolder
    AlphabeticParamsOrder = $true
    WithModulePage = $true
    ExcludeDontShow = $true
    Encoding = [System.Text.Encoding]::UTF8
}
New-MarkdownHelp @parameters

New-MarkdownAboutHelp -OutputFolder $OutputFolder -AboutName "topic_name"
```
Jeśli folder wyjściowy nie istnieje, New-MarkdownHelp tworzy go. W tym przykładzie New-MarkdownHelp tworzony jest plik Markdown dla każdego polecenia cmdlet w module. Tworzy również stronę modułu w pliku o nazwie <ModuleName>.md. Ta strona modułu zawiera listę poleceń cmdlet zawartych w module i symbolach zastępczych opisu synopsis . Metadane na stronie modułu pochodzą z manifestu modułu i są używane przez platformę PlatyPS do utworzenia pliku XML HelpInfo (jak wyjaśniono poniżej).

New-MarkdownAboutHelp Tworzy nowy plik o nazwie about_topic_name.md.

Aby uzyskać więcej informacji, zobacz New-MarkdownHelp i New-MarkdownAboutHelp.

Aktualizowanie istniejącej zawartości języka Markdown po zmianie modułu

Platforma PlatyPS może również aktualizować istniejące pliki języka Markdown dla modułu. Użyj tego kroku, aby zaktualizować istniejące moduły, które mają nowe polecenia cmdlet, nowe parametry lub parametry, które uległy zmianie.

Zaimportuj nowy moduł do sesji. Powtórz ten krok dla każdego modułu, który należy udokumentować.

Uruchom następujące polecenie, aby zaimportować moduły:
```
Import-Module <your module name>
```
Użyj platformy PlatyPS, aby zaktualizować pliki języka Markdown dla strony docelowej modułu i wszystkie skojarzone polecenia cmdlet w module. Powtórz ten krok dla każdego modułu, który należy udokumentować.
```
$parameters = @{
    Path = <folder with Markdown>
    RefreshModulePage = $true
    AlphabeticParamsOrder = $true
    UpdateInputOutput = $true
    ExcludeDontShow = $true
    LogPath = <path to store log file>
    Encoding = [System.Text.Encoding]::UTF8
}
Update-MarkdownHelpModule @parameters
```
Update-MarkdownHelpModule aktualizuje pliki cmdlet i markdown modułu w określonym folderze. Nie aktualizuje about_*.md plików. Plik modułu (ModuleName.md) otrzymuje dowolny nowy tekst synopsis , który został dodany do plików poleceń cmdlet. Aktualizacje pliki poleceń cmdlet obejmują następującą zmianę:
- Nowe zestawy parametrów
- Nowe parametry
- Zaktualizowano metadane parametrów
- Zaktualizowane informacje o typie danych wejściowych i wyjściowych
Aby uzyskać więcej informacji, zobacz Update-MarkdownHelpModule.

Edytowanie nowych lub zaktualizowanych plików języka Markdown

PlatyPS dokumentuje składnię zestawów parametrów i poszczególnych parametrów. Nie może tworzyć opisów ani udostępniać przykładów. Określone obszary, w których potrzebna jest zawartość, znajdują się w nawiasach klamrowych. Na przykład: {{ Fill in the Description }}

Szablon języka Markdown przedstawiający symbole zastępcze w programie VS Code

Musisz dodać synopsis, opis polecenia cmdlet, opisy dla każdego parametru i co najmniej jeden przykład.

Aby uzyskać szczegółowe informacje na temat pisania zawartości programu PowerShell, zobacz następujące artykuły:

Uwaga

Platforma PlatyPS ma określony schemat używany do dokumentacji poleceń cmdlet. Ten schemat zezwala tylko na niektóre bloki języka Markdown w określonych sekcjach dokumentu. Jeśli umieścisz zawartość w niewłaściwej lokalizacji, krok kompilacji PlatyPS zakończy się niepowodzeniem. Aby uzyskać więcej informacji, zobacz dokumentację schematu w repozytorium PlatyPS. Aby zapoznać się z kompletnym przykładem dobrze sformułowanego odwołania do poleceń cmdlet, zobacz Get-Item.

Po podaniu wymaganej zawartości dla każdego z poleceń cmdlet należy się upewnić, że zaktualizowano stronę docelową modułu. Sprawdź, czy moduł ma poprawne Module Guid wartości i Download Help Link w metadanych <module-name>.md YAML pliku. Dodaj brakujące metadane.

Ponadto możesz zauważyć, że niektóre polecenia cmdlet mogą brakować synopsis (krótki opis). Następujące polecenie aktualizuje stronę docelową modułu przy użyciu tekstu opisu synopsis . Otwórz stronę docelową modułu, aby zweryfikować opisy.

Update-MarkdownHelpModule -Path <full path output folder> -RefreshModulePage

Po wprowadzeniu całej zawartości możesz utworzyć pliki pomocy MAML wyświetlane Get-Help w konsoli programu PowerShell.

Tworzenie plików pomocy zewnętrznej

Ten krok tworzy pliki pomocy MAML wyświetlane Get-Help w konsoli programu PowerShell.

Aby skompilować pliki MAML, uruchom następujące polecenie:

New-ExternalHelp -Path <folder with MDs> -OutputPath <output help folder>

New-ExternalHelp Konwertuje wszystkie pliki języka Markdown poleceń cmdlet na jeden (lub więcej) plików MAML. Informacje o plikach są konwertowane na pliki zwykłego tekstu o następującym formacie nazwy: about_topic_name.help.txt. Zawartość języka Markdown musi spełniać wymagania schematu PlatyPS. New-ExternalHelp kończy działanie z błędami, gdy zawartość nie jest zgodna ze schematem. Aby naprawić naruszenia schematu, należy edytować pliki.

Przestroga

PlatyPS wykonuje słabe zadanie konwertowania about_*.md plików na zwykły tekst. Aby uzyskać dopuszczalne wyniki, musisz użyć bardzo prostego języka Markdown. Możesz zachować pliki w formacie zwykłego tekstu about_topic_name.help.txt , a nie umożliwić platformie PlatyPS ich konwertowanie.

Po zakończeniu tego kroku zobaczysz *-help.xml pliki w about_*.help.txt docelowym folderze danych wyjściowych.

Aby uzyskać więcej informacji, zobacz New-ExternalHelp

Testowanie skompilowanych plików pomocy

Zawartość można sprawdzić za pomocą polecenia cmdlet Get-HelpPreview :

Get-HelpPreview -Path "<ModuleName>-Help.xml"

Polecenie cmdlet odczytuje skompilowany plik MAML i wyświetla zawartość w tym samym formacie, który otrzymasz od Get-Helpprogramu . Dzięki temu można sprawdzić wyniki, aby sprawdzić, czy pliki markdown zostały skompilowane poprawnie i wygenerować żądane wyniki. Jeśli wystąpi błąd, ponownie zmodyfikuj pliki markdown i ponownie skompiluj aplikację MAML.

Teraz możesz opublikować pliki pomocy.

Publikowanie pomocy

Teraz, gdy pliki języka Markdown zostały skompilowane do plików pomocy programu PowerShell, możesz przystąpić do udostępniania plików użytkownikom. Istnieją dwie opcje zapewniania pomocy w konsoli programu PowerShell.

Spakuj pliki pomocy za pomocą modułu
Tworzenie pakietu pomocy z możliwością aktualizacji instalowanego przez użytkowników za pomocą Update-Help polecenia cmdlet

Pomoc dotycząca pakowania modułu

Pliki pomocy można spakować za pomocą modułu. Aby uzyskać szczegółowe informacje o strukturze folderów, zobacz Pisanie pomocy dla modułów . W manifeście modułu należy dołączyć listę plików Pomocy w wartości klucza FileList .

Tworzenie pakietu pomocy z możliwością aktualizacji

Na wysokim poziomie kroki tworzenia pomocy z możliwością aktualizacji obejmują:

Znajdowanie witryny internetowej do hostowania plików pomocy
Dodawanie klucza HelpInfoURI do manifestu modułu
Tworzenie pliku XML HelpInfo
Tworzenie plików CAB
Przekazywanie plików

Aby uzyskać więcej informacji, zobacz Obsługa pomocy z możliwością aktualizacji: krok po kroku.

Platforma PlatyPS ułatwia wykonanie niektórych z tych kroków.

Identyfikator HelpInfoURI to adres URL wskazujący lokalizację, w której pliki pomocy są hostowane w Internecie. Ta wartość jest skonfigurowana w manifeście modułu. Update-Help Odczytuje manifest modułu, aby uzyskać ten adres URL i pobrać zawartość pomocy z możliwością aktualizacji. Ten adres URL powinien wskazywać tylko lokalizację folderu, a nie poszczególne pliki. Update-Help tworzy nazwy plików do pobrania na podstawie innych informacji z manifestu modułu i pliku XML HelpInfo.

Ważne

Identyfikator HelpInfoURI musi kończyć się znakiem ukośnika (/). Bez tego znaku Update-Help nie można skonstruować prawidłowych ścieżek plików w celu pobrania zawartości. Ponadto większość usług plików opartych na protokole HTTP jest rozróżniana wielkość liter. Ważne jest, aby metadane modułu w pliku XML HelpInfo zawierały prawidłowy przypadek litery.

Polecenie New-ExternalHelp cmdlet tworzy plik XML HelpInfo w folderze wyjściowym. Plik XML HelpInfo jest kompilowany przy użyciu metadanych YAML zawartych w plikach języka Markdown modułu (ModuleName.md).

Polecenie New-ExternalHelpCab cmdlet tworzy pliki ZIP i CAB zawierające skompilowane pliki MAML i about_*.help.txt pliki. Pliki CAB są zgodne ze wszystkimi wersjami programu PowerShell. Program PowerShell 6 lub nowszy może używać plików ZIP.

$helpCabParameters = @{
    CabFilesFolder = $MamlOutputFolder
    LandingPagePath = $LandingPage
    OutputFolder = $CabOutputFolder
}
New-ExternalHelpCab @helpCabParameters

Po utworzeniu plików ZIP i CAB przekaż pliki XML ZIP, CAB i HelpInfo do serwera plików HTTP. Umieść pliki w lokalizacji wskazanej przez identyfikator HelpInfoURI.

Aby uzyskać więcej informacji, zobacz New-ExternalHelpCab.

Inne opcje publikowania

Markdown to wszechstronny format, który można łatwo przekształcić w inne formaty publikowania. Za pomocą narzędzia, takiego jak Pandoc, można przekonwertować pliki pomocy języka Markdown na wiele różnych formatów dokumentów, w tym zwykły tekst, HTML, PDF i Office.

Ponadto polecenia cmdlet ConvertFrom-Markdown i Show-Markdown w programie PowerShell 6 i nowszym mogą służyć do konwertowania języka Markdown na kod HTML lub tworzenia kolorowego wyświetlania w konsoli programu PowerShell.

Znane problemy

Platforma PlatyPS jest bardzo wrażliwa na schemat struktury plików Języka Markdown tworzonych i kompilowanych. Bardzo łatwo jest napisać prawidłowy kod Markdown, który narusza ten schemat. Aby uzyskać więcej informacji, zobacz przewodnik po stylu programu PowerShell i artykuły referencyjne dotyczące edytowania.