Pisanie pomocy dotyczącej modułów programu PowerShell

  • Artykuł

Moduły programu PowerShell mogą zawierać tematy pomocy dotyczące modułu i jego elementów członkowskich, takie jak polecenia cmdlet, dostawcy, funkcje i skrypty. Polecenie cmdlet wyświetla tematy pomocy modułu w tym samym formacie, w którym wyświetla pomoc dla innych elementów programu PowerShell, a użytkownicy używają standardowych poleceń do uzyskania Get-Help Get-Help tematów pomocy.

W tym dokumencie wyjaśniono format i prawidłową umieszczanie tematów pomocy modułu oraz zasuwają wskazówki dotyczące zawartości pomocy modułu.

Typy pomocy modułu

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

  • Pomoc polecenia cmdlet. Tematy pomocy opisujące polecenia cmdlet w module to pliki XML, które używają schematu pomocy polecenia

  • Pomoc dostawcy. Tematy pomocy opisujące dostawców w module to pliki XML, które używają schematu pomocy dostawcy.

  • Pomoc funkcji. Tematy pomocy opisujące funkcje w module mogą być plikami XML, które używają schematu pomocy polecenia lub tematów pomocy opartych na komentarzach w ramach funkcji albo skryptu lub modułu skryptu

  • Pomoc dla skryptów. Tematy pomocy opisujące skrypty w module mogą być plikami XML, które używają schematu pomocy polecenia lub tematów pomocy opartych na komentarzach w skrypcie lub module skryptu.

  • Koncepcyjna pomoc ("Informacje"). Możesz użyć koncepcyjnego tematu pomocy ("about"), aby opisać moduł i jego elementy członkowskie oraz wyjaśnić, jak składowe mogą być używane razem do wykonywania zadań. Tematy pomocy koncepcyjnej to pliki tekstowe z kodowaniem Unicode (UTF-8). Nazwa pliku musi mieć about_<name>.help.txt format, taki jak about_MyModule.help.txt . Domyślnie program PowerShell zawiera ponad 100 tych koncepcyjnych tematów pomocy i są one sformatowane tak, jak w poniższym przykładzie.

    TOPIC
    about_<subject or module name>

SHORT DESCRIPTION
    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.

KEYWORDS
    Terms or titles on which you might expect your users to search for the information in this topic.

SEE ALSO
    Text-only references for further reading. Hyperlinks cannot work in the PowerShell console.

Wszystkie pliki schematu można znaleźć w $PSHOME\Schemas\PSMaml folderze .

Umieszczanie pomocy modułu

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

Na przykład na poniższym diagramie struktury katalogów przedstawiono 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

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

Uzyskiwanie pomocy 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 polecenie cmdlet nie ma wpływu na Export-ModuleMember tematy pomocy.

Tematy pomocy modułu można udostępnić w różnych językach. Polecenie cmdlet automatycznie wyświetla tematy pomocy modułu w języku określonym dla bieżącego użytkownika w pozycji Opcje regionalne i językowe w Get-Help Panel sterowania. W Windows Vista i nowszych wersjach programu Windows program wyszukuje tematy Pomocy w podkatalogach modułu specyficznych dla języka zgodnie ze standardami rezerwy języka określonymi dla Get-Help Windows.

Począwszy od programu PowerShell 3.0 uruchomienie polecenia cmdlet lub funkcji wyzwala automatyczne Get-Help 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, wyświetla automatycznie Get-Help wygenerowaną pomoc. Automatycznie wygenerowana pomoc zawiera składnię poleceń, parametry oraz typy danych wejściowych i wyjściowych, ale nie zawiera żadnych opisów. Automatycznie wygenerowana pomoc zawiera tekst, który kieruje użytkownika do próby użycia polecenia cmdlet w celu pobrania pomocy dotyczącej polecenia z Internetu lub Update-Help udziału plików. Zaleca się również użycie parametru Online polecenia cmdlet w celu uzyskania Get-Help wersji online tematu pomocy.

Obsługa aktualizowalnej pomocy

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

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

Autorzy modułów mogą dołączać pliki pomocy do modułu i używać Aktualizowalnia pomocy do aktualizowania plików pomocy lub pomijać pliki pomocy z modułu i używać aktualizowalnie pomocy zarówno do ich instalowania, jak i aktualizowania.

Aby uzyskać więcej informacji na temat pomocy, która może być dowaalna, zobacz Supporting Updatable Help (Pomoc techniczna dla dziegieć).

Obsługa pomocy 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ących modułu w wersji online. Parametr online polecenia cmdlet otwiera wersję online polecenia cmdlet lub tematu pomocy funkcji zaawansowanej dla użytkownika Get-Help w domyślnej przeglądarce internetowej.

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

Począwszy od programu PowerShell 3.0, można ułatwić użytkownikom znajdowanie online wersji polecenia cmdlet i funkcji tematy pomocy, definiując atrybut HelpUri klasy polecenia 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 Supporting Online Help.

Zobacz też

Pisanie modułu programu PowerShell

Obsługa aktualizowalnej pomocy

Obsługa pomocy online