Udostępnij za pomocą

Pisanie pomocy dotyczącej modułów programu PowerShell

Moduły programu PowerShell mogą zawierać tematy Pomocy dotyczące modułu i elementów członkowskich modułu, takie jak polecenia cmdlet, dostawcy, funkcje i skrypty. Polecenie Get-Help cmdlet wyświetla tematy Pomocy modułu w tym samym formacie, w jakim wyświetla Pomoc dla innych elementów programu PowerShell, a użytkownicy używają standardowych Get-Help poleceń, aby uzyskać tematy Pomocy.

W tym dokumencie wyjaśniono format i poprawne rozmieszczenie tematów Pomocy modułu oraz sugerowano wskazówki dotyczące zawartości Pomocy modułu.

Typy pomocy modułu

Moduł może zawierać następujące typy Pomocy.

  • Pomoc oparta na formacie XML

    • Pomoc dotycząca poleceń cmdlet. Tematy Pomocy opisujące polecenia cmdlet w module to pliki XML korzystające ze schematu pomocy polecenia
    • Pomoc dostawcy. Tematy Pomocy opisujące dostawców w module to pliki XML korzystające ze schematu pomocy dostawcy.
    • Pomoc funkcji. Tematy Pomocy opisujące funkcje w module mogą być plikami XML, które używają schematu pomocy poleceń lub tematów Pomocy opartej na komentarzach w funkcji, skryptu lub skryptu
    • Pomoc dotycząca skryptu. Tematy Pomocy opisujące skrypty w module mogą być plikami XML korzystającymi ze schematu pomocy poleceń lub tematów pomocy opartych na komentarzach w module skryptu lub skryptu.
    • Folder $PSHOME\Schemas\PSMaml zawiera pliki schematu, które definiują format XML.

  • Pliki tekstowe pomocy koncepcyjnej ("Informacje")

    Możesz użyć tematu pomocy koncepcyjnej ("about"), aby opisać moduł i jego członków oraz wyjaśnić, jak członkowie mogą być używane razem do wykonywania zadań. Domyślnie program PowerShell zawiera ponad 100 tych pojęć dotyczących tematów Pomocy. Nazwa pliku musi używać about_<name>.help.txt formatu, takiego jak about_MyModule.help.txt.

    Uwaga / Notatka

    Nagłówek TOPIC sekcji musi rozpoczynać się w pierwszej kolumnie pierwszego wiersza pliku. Zawartość sekcji w drugim wierszu powinna być zgodna z nazwą pliku bez sufiksu .help.txt . Musisz wcięć zawartość dokładnie 4 spacje. Trzeci wiersz musi być pusty. Nagłówek SYNOPSIS sekcji musi zaczynać się w pierwszej kolumnie czwartego wiersza. Musisz wcięć zawartość w piątym wierszu dokładnie 4 spacje. Te wymagania są niezbędne do poprawnego rozpoznawania zawartości przez Get-Help polecenie cmdlet .

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    Poniższy przykładowy szablon można użyć jako punktu wyjścia do pisania pojęć dotyczących tematów Pomocy. Z wyjątkiem dwóch pierwszych sekcji struktura koncepcyjnych tematów Pomocy jest dowolna. Pozostałe tytuły sekcji mogą być odpowiednie dla zawartości.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    Możesz użyć dowolnego stylu i znaczników, ale program PowerShell widzi go jako zwykły tekst i nie ma specjalnego renderowania tekstu w konsoli programu PowerShell. Poniższe sugestie zapewniają najlepsze wyniki wyświetlania i czytelność.

    • Użyj kodowania UTF-8 z kodowaniem BOM, aby upewnić się, że wszystkie specjalne znaki (wielo bajtowe) są wyświetlane poprawnie.
    • Podkreśl nagłówki sekcji lub użyj wszystkich wielkich liter, aby wyróżnić je. Ułatwia to skanowanie zawartości.
    • Ogranicz długość każdego wiersza do 80 znaków.
    • Wcięcie bloków kodu i przykładowych danych wyjściowych, aby oddzielić je od otaczającej prozy.

Umieszczanie pomocy modułu

Polecenie Get-Help cmdlet wyszukuje pliki tematów pomocy modułu w podkatalogach specyficznych dla języka katalogu modułu.

Na przykład poniższy diagram struktury katalogów przedstawia lokalizację tematów Pomocy dla modułu SampleModule.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Uwaga / Notatka

W tym przykładzie <ModulePath> symbol zastępczy reprezentuje jedną ze ścieżek w PSModulePath zmiennej środowiskowej, na przykład $HOME\Documents\Modules, $PSHOME\Moduleslub niestandardową ścieżkę określaną przez użytkownika.

Uzyskiwanie pomocy dotyczącej modułu

Gdy użytkownik importuje moduł do sesji, tematy Pomocy dla tego modułu są importowane do sesji wraz z modułem. Pliki tematów Pomocy można wyświetlić w wartości klucza FileList w manifeście modułu, ale tematy Pomocy nie mają wpływu na Export-ModuleMember polecenie cmdlet.

Tematy pomocy modułu można udostępniać w różnych językach. Polecenie Get-Help cmdlet automatycznie wyświetla tematy Pomocy modułu w języku określonym dla bieżącego użytkownika w elemencie Opcje regionalne i językowe w Panelu sterowania. W systemie Windows Vista i nowszych wersjach systemu Windows Get-Help wyszukuje tematy Pomocy w podkatalogach specyficznych dla języka katalogu modułu zgodnie ze standardami rezerwowymi języka ustalonymi dla systemu Windows.

Począwszy od programu PowerShell 3.0, uruchomienie Get-Help polecenia cmdlet lub funkcji wyzwala automatyczne importowanie modułu. Polecenie Get-Help cmdlet natychmiast wyświetla zawartość tematów pomocy w module.

Jeśli moduł nie zawiera tematów pomocy i nie ma tematów pomocy dotyczących poleceń w module na komputerze użytkownika, Get-Help zostanie wyświetlona automatycznie wygenerowana pomoc. Automatycznie wygenerowana pomoc obejmuje składnię poleceń, parametry i typy danych wejściowych i wyjściowych, ale nie zawierają żadnych opisów. Automatycznie wygenerowana pomoc zawiera tekst, który kieruje użytkownika do próby użycia Update-Help polecenia cmdlet w celu pobrania pomocy dla polecenia z Internetu lub udziału plików. Zaleca się również użycie parametru Get-Help polecenia cmdlet w celu uzyskania wersji online tematu pomocy.

Obsługa aktualizowalnej pomocy

Użytkownicy programu PowerShell w wersji 3.0 lub nowszej programu PowerShell mogą pobierać i instalować zaktualizowane pliki pomocy dla modułu z Internetu lub z lokalnego udziału plików. Polecenia Update-Help cmdlet i Save-Help ukrywają szczegóły zarządzania przed użytkownikiem. Użytkownicy uruchamiają Update-Help polecenie cmdlet, a następnie używają Get-Help polecenia cmdlet, aby odczytać najnowsze pliki pomocy dla modułu w wierszu polecenia programu PowerShell. Użytkownicy nie muszą ponownie uruchamiać systemu Windows ani programu PowerShell.

Użytkownicy za zaporami i osoby bez dostępu do Internetu mogą również korzystać z dostępnej pomocy. Administratorzy z dostępem do Internetu używają Save-Help polecenia cmdlet do pobierania i instalowania najnowszych plików pomocy w udziale plików. Następnie użytkownicy używają parametru Update-Help polecenia cmdlet, aby uzyskać najnowsze pliki pomocy z udziału plików.

Autorzy modułów mogą dołączać pliki pomocy w module i używać aktualizowalnej pomocy, aby zaktualizować pliki pomocy, lub pominąć pliki pomocy z modułu i użyć aktualizowalnej pomocy zarówno do zainstalowania, jak i zaktualizowania.

Aby uzyskać więcej informacji na temat aktualizowalnej pomocy, zobacz Obsługa aktualizowalnej pomocy.

Pomoc w trybie online

Użytkownicy, którzy nie mogą lub nie instalują zaktualizowanych plików pomocy na swoich komputerach, często korzystają z tematów pomocy dotyczącej wersji online modułu. Parametr Get-Help polecenia cmdlet otwiera wersję online polecenia cmdlet lub temat pomocy zaawansowanej funkcji dla użytkownika w domyślnej przeglądarce internetowej.

Polecenie Get-Help cmdlet używa wartości właściwości HelpUri polecenia cmdlet lub funkcji, aby znaleźć wersję online tematu pomocy.

Począwszy od programu PowerShell 3.0, możesz ułatwić użytkownikom znajdowanie wersji online poleceń cmdlet i tematów pomocy funkcji przez zdefiniowanie atrybutu HelpUri w klasie cmdlet lub właściwości HelpUri atrybutu CmdletBinding . Wartość atrybutu jest wartością właściwości HelpUri polecenia cmdlet lub funkcji.

Aby uzyskać więcej informacji, zobacz Obsługa pomocy online.

Zobacz też

  • Last updated on