Nadawanie nazw plikom pomocyNaming Help Files

W tym temacie wyjaśniono, jak nazwać plik pomocy oparty na języku XML, aby można go było znaleźć w poleceniu cmdlet Get-Help .This topic explains how to name an XML-based help file so that the Get-Help cmdlet can find it. Wymagania dotyczące nazw różnią się w zależności od typu polecenia.The name requirements differ for each command type.

Pliki pomocy poleceń cmdletCmdlet Help Files

Plik pomocy dla polecenia cmdlet języka C# musi mieć nazwę zestawu, w którym jest zdefiniowane polecenie cmdlet.The help file for a C# cmdlet must be named for the assembly in which the cmdlet is defined. Użyj następującego formatu nazwy pliku:Use the following filename format:

<AssemblyName>.dll-help.xml

Format nazwy zestawu jest wymagany nawet wtedy, gdy zestaw jest modułem zagnieżdżonym.The assembly name format is required even when the assembly is a nested module.

Na przykład polecenie cmdlet Get-WinEvent jest zdefiniowane w zestawie Microsoft.PowerShell.Diagnostics.dll.For example, the Get-WinEvent cmdlet is defined in the Microsoft.PowerShell.Diagnostics.dll assembly. Get-HelpPolecenie cmdlet szuka tematu pomocy dotyczącego Get-WinEvent polecenia cmdlet tylko w Microsoft.PowerShell.Diagnostics.dll-help.xml pliku w katalogu modułów.The Get-Help cmdlet looks for a help topic for the Get-WinEvent cmdlet only in the Microsoft.PowerShell.Diagnostics.dll-help.xml file in the module directory.

Pliki pomocy dostawcyProvider Help files

Plik pomocy dla dostawcy programu PowerShell musi mieć nazwę zestawu, w którym jest zdefiniowany dostawca.The help file for a PowerShell provider must be named for the assembly in which the provider is defined. Użyj następującego formatu nazwy pliku:Use the following filename format:

<AssemblyName>.dll-help.xml

Format nazwy zestawu jest wymagany nawet wtedy, gdy zestaw jest modułem zagnieżdżonym.The assembly name format is required even when the assembly is a nested module.

Na przykład dostawca certyfikatów jest zdefiniowany w Microsoft.PowerShell.Security.dll zestawie.For example, the Certificate provider is defined in the Microsoft.PowerShell.Security.dll assembly. Get-HelpPolecenie cmdlet szuka tematu pomocy dla dostawcy certyfikatów tylko w Microsoft.PowerShell.Security.dll-help.xml pliku w katalogu modułów.The Get-Help cmdlet looks for a help topic for the Certificate provider only in the Microsoft.PowerShell.Security.dll-help.xml file in the module directory.

Pliki pomocy funkcjiFunction Help Files

Funkcje mogą być dokumentowane przy użyciu pomocy opartej na komentarzach lub udokumentowane w pliku pomocy XML.Functions can be documented by using comment-based help or documented in an XML help file. Gdy funkcja jest udokumentowana w pliku XML, funkcja musi mieć .ExternalHelp słowo kluczowe Comment, które kojarzy funkcję z plikiem XML.When the function is documented in an XML file, the function must have an .ExternalHelp comment keyword that associates the function with the XML file. W przeciwnym razie Get-Help polecenie cmdlet nie może odnaleźć pliku pomocy.Otherwise, the Get-Help cmdlet cannot find the help file.

Nie ma wymagań technicznych dotyczących nazwy pliku pomocy funkcji.There are no technical requirements for the name of a function help file. Jednak najlepszym rozwiązaniem jest nazwa pliku pomocy dla modułu skryptu, w którym zdefiniowano funkcję.However, a best practice is to name the help file for the script module in which the function is defined. Na przykład następująca funkcja jest zdefiniowana w MyModule.psm1 pliku.For example, the following function is defined in the MyModule.psm1 file.

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

Pliki pomocy poleceń CIMCIM Command Help Files

Plik pomocy dla polecenia CIM musi być nazwany dla pliku CDXML, w którym jest zdefiniowane polecenie CIM.The help file for a CIM command must be named for the CDXML file in which the CIM command is defined. Użyj następującego formatu nazwy pliku:Use the following filename format:

<FileName>.cdxml-help.xml

Polecenia CIM są zdefiniowane w plikach CDXML, które mogą być dołączone do modułów jako moduły zagnieżdżone.CIM commands are defined in CDXML files that can be included in modules as nested modules. Gdy polecenie CIM jest importowane do sesji jako funkcja, program PowerShell dodaje .ExternalHelp słowo kluczowe Comment do definicji funkcji, która kojarzy funkcję z plikiem pomocy XML o nazwie dla pliku CDXML, w którym jest zdefiniowane polecenie CIM.When the CIM command is imported into the session as a function, PowerShell adds an .ExternalHelp comment keyword to the function definition that associates the function with an XML help file that is named for the CDXML file in which the CIM command is defined.

Pliki pomocy przepływu pracy skryptuScript Workflow Help Files

Przepływy pracy skryptów, które znajdują się w modułach, mogą być udokumentowane w plikach pomocy opartych na języku XML.Script workflows that are included in modules can be documented in XML-based help files. Nie ma wymagań technicznych dotyczących nazwy pliku pomocy.There are no technical requirements for the name of the help file. Jednak najlepszym rozwiązaniem jest nazwa pliku pomocy dla modułu skryptu, w którym jest zdefiniowany przepływ pracy skryptu.However, a best practice is to name the help file for the script module in which the script workflow is defined. Na przykład:For example:

<ScriptModule>.psm1-help.xml

W przeciwieństwie do innych poleceń skryptu, przepływy pracy skryptów nie wymagają .ExternalHelp słowa kluczowego komentarza, aby skojarzyć je z plikiem pomocy.Unlike other scripted commands, script workflows do not require an .ExternalHelp comment keyword to associate them with a help file. Zamiast tego program PowerShell szuka podkatalogów specyficznych dla kultury interfejsu użytkownika katalogu modułów dla plików pomocy opartych na języku XML i szuka pomocy dla przepływu pracy skryptu we wszystkich plikach.Instead, PowerShell searches the UI-Culture-specific subdirectories of the module directory for XML-based help files and looks for help for the script workflow in all the files. .ExternalHelp słowo kluczowe comment jest ignorowane..ExternalHelp comment keyword are ignored.

Ponieważ .ExternalHelp słowo kluczowe comment jest ignorowane, Get-Help polecenie cmdlet może znaleźć pomoc dla skryptów przepływów pracy tylko wtedy, gdy znajdują się one w modułach.Because the .ExternalHelp comment keyword is ignored, the Get-Help cmdlet can find help for script workflows only when they are included in modules.