命名帮助文件

笔记

手动编写基于 XML 的帮助非常困难。 PlatyPS 模块允许您在 Markdown 中编写帮助，然后将其转换为基于 XML 的帮助。这使得编写和维护帮助变得更加容易。 PlatyPS 还可以为您创建可更新的帮助包。有关详细信息，请参阅使用 PlatyPS 创建基于 XML 的帮助。

本主题说明如何命名基于 XML 的帮助文件，以便 Get-Help cmdlet 可以找到它。每种命令类型的名称要求有所不同。

Cmdlet 帮助文件

C# cmdlet 的帮助文件必须以定义该 cmdlet 的程序集命名。使用以下文件名格式：

<AssemblyName>.dll-help.xml

即使程序集是嵌套模块，程序集名称格式也是必需的。

例如，Get-WinEvent cmdlet 是在 Microsoft.PowerShell.Diagnostics.dll 程序集中定义的。 Get-Help cmdlet 仅在 Microsoft.PowerShell.Diagnostics.dll-help.xml 中查找 Get-WinEvent cmdlet 的帮助主题> 模块目录中的文件。

提供商帮助文件

PowerShell 提供程序的帮助文件必须以定义该提供程序的程序集命名。使用以下文件名格式：

<AssemblyName>.dll-help.xml

即使程序集是嵌套模块，程序集名称格式也是必需的。

例如，证书提供程序在 Microsoft.PowerShell.Security.dll 程序集中定义。 Get-Help cmdlet 仅在模块目录的 Microsoft.PowerShell.Security.dll-help.xml 文件中查找证书提供程序的帮助主题。

功能帮助文件

可以使用基于注释的帮助来记录功能，也可以将其记录在 XML 帮助文件中。当函数记录在 XML 文件中时，该函数必须具有将函数与 XML 文件关联起来的 .ExternalHelp 注释关键字。否则，Get-Help cmdlet 无法找到帮助文件。

函数帮助文件的名称没有技术要求。但是，最佳实践是为定义该函数的脚本模块命名帮助文件。例如，MyModule.psm1 文件中定义了以下函数。

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

CIM 命令帮助文件

CIM 命令的帮助文件必须以定义 CIM 命令的 CDXML 文件命名。使用以下文件名格式：

<FileName>.cdxml-help.xml

CIM 命令在 CDXML 文件中定义，这些文件可以作为嵌套模块包含在模块中。当 CIM 命令作为函数导入到会话中时，PowerShell 会向函数定义添加一个 .ExternalHelp 注释关键字，该注释关键字将函数与以 CDXML 文件命名的 XML 帮助文件关联起来，其中CIM 命令已定义。

脚本工作流程帮助文件

模块中包含的脚本工作流程可以记录在基于 XML 的帮助文件中。帮助文件的名称没有技术要求。但是，最佳实践是为定义脚本工作流的脚本模块命名帮助文件。例如：

<ScriptModule>.psm1-help.xml

与其他脚本命令不同，脚本工作流不需要 .ExternalHelp 注释关键字将它们与帮助文件关联。相反，PowerShell 会在模块目录的 UI-Culture 特定子目录中搜索基于 XML 的帮助文件，并在所有文件中查找脚本工作流程的帮助。 .ExternalHelp 注释关键字将被忽略。

由于 .ExternalHelp 注释关键字被忽略，因此 Get-Help cmdlet 仅当脚本工作流包含在模块中时才能查找它们的帮助。