Nadawanie nazw plikom pomocy

  • Artykuł

W tym temacie wyjaśniono, jak nazwać plik pomocy oparty na formacie XML, aby można go było znaleźć za pomocą polecenia cmdlet Get-Help. Wymagania dotyczące nazw różnią się dla każdego typu polecenia.

Pliki pomocy dla polecenia cmdlet

Plik pomocy dla polecenia cmdlet języka C# musi mieć nazwę zestawu, w którym zdefiniowano polecenie cmdlet. Użyj następującego formatu nazwy pliku:

<AssemblyName>.dll-help.xml

Format nazwy zestawu jest wymagany nawet wtedy, gdy zestaw jest modułem zagnieżdżanym.

Na przykład polecenie cmdlet Get-WinEvent jest zdefiniowane w Microsoft.PowerShell.Diagnostics.dll zestawie. Polecenie cmdlet szuka tematu pomocy dla polecenia Get-Help cmdlet tylko w pliku w katalogu Get-WinEvent Microsoft.PowerShell.Diagnostics.dll-help.xml modułu.

Pliki pomocy dostawcy

Plik pomocy dla dostawcy programu PowerShell musi mieć nazwę zestawu, w którym dostawca jest zdefiniowany. Użyj następującego formatu nazwy pliku:

<AssemblyName>.dll-help.xml

Format nazwy zestawu jest wymagany nawet wtedy, gdy zestaw jest modułem zagnieżdżanym.

Na przykład dostawca certyfikatów jest zdefiniowany w Microsoft.PowerShell.Security.dll zestawie. Polecenie cmdlet szuka tematu pomocy dla dostawcy certyfikatów tylko w Get-Help Microsoft.PowerShell.Security.dll-help.xml pliku w katalogu modułu.

Pliki pomocy funkcji

Funkcje mogą być udokumentowane przy użyciu pomocy opartej na komentarzach lub udokumentowane w pliku pomocy XML. Gdy funkcja jest udokumentowana w pliku XML, funkcja musi mieć słowo kluczowe komentarza, które kojarzy funkcję .ExternalHelp z plikiem XML. W przeciwnym razie Get-Help polecenie cmdlet nie może znaleźć pliku pomocy.

Nie ma żadnych wymagań technicznych dotyczących nazwy pliku pomocy funkcji. Jednak najlepszym rozwiązaniem jest nazwanie pliku pomocy dla modułu skryptu, w którym zdefiniowano funkcję. Na przykład następująca funkcja jest zdefiniowana w MyModule.psm1 pliku .

#.ExternalHelp MyModule.psm1-help.xml
function Test-Function { ... }

Pliki pomocy poleceń CIM

Plik pomocy dla polecenia MODELU CIM musi mieć nazwę pliku CDXML, w którym zdefiniowano polecenie CIM. Użyj następującego formatu nazwy pliku:

<FileName>.cdxml-help.xml

Polecenia modelu CIM są definiowane w plikach CDXML, które mogą być zawarte w modułach jako moduły zagnieżdżone. Gdy polecenie CIM jest importowane do sesji jako funkcja, program PowerShell dodaje słowo kluczowe komentarza do definicji funkcji, która kojarzy funkcję z plikiem pomocy XML o nazwie dla pliku CDXML, w którym zdefiniowano polecenie .ExternalHelp CIM.

Pliki pomocy przepływu pracy skryptu

Przepływy pracy skryptów, które są zawarte w modułach, można o dokumentować w plikach pomocy opartych na formacie XML. Nazwa pliku pomocy nie ma wymagań technicznych. Jednak najlepszym rozwiązaniem jest nazwanie pliku pomocy dla modułu skryptu, w którym zdefiniowano przepływ pracy skryptu. Na przykład:

<ScriptModule>.psm1-help.xml

W przeciwieństwie do innych poleceń skryptowych przepływy pracy skryptów nie wymagają słowa kluczowego komentarza do skojarzenia ich .ExternalHelp z plikiem pomocy. Zamiast tego program PowerShell wyszukuje podkatalogi specyficzne dla kultury interfejsu użytkownika w katalogu modułu dla plików pomocy opartych na formacie XML i szuka pomocy dotyczącej przepływu pracy skryptu we wszystkich plikach. .ExternalHelp Słowo kluczowe komentarza jest ignorowane.

Ponieważ słowo .ExternalHelp kluczowe komentarza jest ignorowane, polecenie cmdlet może znaleźć pomoc dla przepływów pracy skryptów tylko wtedy, gdy Get-Help są one zawarte w modułach.