编写针对 PowerShell 模块的帮助

  • 项目

PowerShell 模块可以包含有关模块和模块成员（如 cmdlet、提供程序、函数和脚本）的帮助主题。 cmdlet 以与显示其他 PowerShell 项的帮助相同的格式显示模块帮助主题，并且用户使用标准命令 Get-Help Get-Help 获取帮助主题。

本文档介绍模块帮助主题的格式和正确位置，并建议模块帮助内容的准则。

模块帮助的类型

模块可以包含以下类型的帮助。

  • Cmdlet 帮助。 描述模块中的 cmdlet 的帮助主题是使用命令帮助架构的 XML 文件

  • 提供程序帮助。 描述模块中的提供程序的帮助主题是使用提供程序帮助架构的 XML 文件。

  • 函数帮助。 描述模块中函数的帮助主题可以是 XML 文件，这些文件使用命令帮助架构或函数中基于注释的帮助主题，或者脚本或脚本模块

  • 脚本帮助。 描述模块中脚本的帮助主题可以是 XML 文件，这些文件使用命令帮助架构或脚本模块中基于注释的帮助主题。

  • 概 ("关于") 帮助。 可以使用概念 ("about") 帮助主题来描述模块及其成员，并说明如何将成员一起用于执行任务。 概念帮助主题是使用 Unicode (UTF-8) 文本文件。 文件名必须使用 格式 about_<name>.help.txt ，例如 about_MyModule.help.txt 。 默认情况下，PowerShell 包含这些概念性"关于帮助"主题中的 100 多个，格式如下例所示。

    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.

所有架构文件都可以在 文件夹中 $PSHOME\Schemas\PSMaml 找到。

模块帮助的位置

Get-Helpcmdlet 在模块目录的语言特定子目录中查找模块帮助主题文件。

例如，以下目录结构图显示了 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

备注

在示例中，占位符表示环境变量中的一个路径，例如 、 或用户指定的 <ModulePath> PSModulePath $HOME\Documents\Modules $PSHOME\Modules 自定义路径。

获取模块帮助

当用户将模块导入会话时，该模块的帮助主题将连同模块一起导入到会话中。 可以在模块清单中 FileList 键的值中列出帮助主题文件，但帮助主题不受 Export-ModuleMember cmdlet 的影响。

可以使用不同的语言提供模块帮助主题。 cmdlet 会自动在"区域"和"语言选项"项中显示模块帮助主题，这些主题的语言为当前用户指定的 Get-Help 控制面板。 在 Windows Vista 及更高版本的 Windows 中，根据为 Windows 建立的语言回退标准，在模块目录的语言特定 Get-Help 子目录中搜索帮助主题。

从 PowerShell 3.0 开始，运行 cmdlet 或函数的命令会触发 Get-Help 模块的自动导入。 Get-Helpcmdlet 会立即显示模块中帮助主题的内容。

如果模块不包含帮助主题，并且用户计算机上模块中的命令没有帮助主题，则 Get-Help 显示自动生成的帮助。 自动生成的帮助包括命令语法、参数以及输入和输出类型，但不包含任何说明。 自动生成的帮助包括文本，指示用户尝试使用 cmdlet 从 Internet 或文件共享下载命令 Update-Help 的帮助。 它还建议使用 cmdlet 的 Online 参数 Get-Help 获取帮助主题的联机版本。

支持可更新帮助

PowerShell 3.0 及更高版本的用户可以从 Internet 或本地文件共享下载和安装模块的更新帮助文件。 Update-Help和 Save-Help cmdlet 向用户隐藏管理详细信息。 用户运行 cmdlet，然后使用 cmdlet 在 PowerShell 命令提示符下读取模块 Update-Help Get-Help 最新的帮助文件。 用户无需重启 Windows PowerShell。

防火墙后面的用户和无法访问 Internet 的用户也可使用可更新的帮助。 具有 Internet 访问权限的管理员使用 cmdlet 将最新的帮助文件下载 Save-Help 并安装到文件共享。 然后，用户使用 cmdlet 的 Path 参数从文件共享获取 Update-Help 最新的帮助文件。

模块作者可以在模块中包括帮助文件，并使用可更新的帮助来更新帮助文件，或者省略模块中的帮助文件，并使用可更新的帮助来安装和更新它们。

有关可更新帮助的信息，请参阅 Supporting Updatable Help。

支持联机帮助

无法或不在计算机上安装更新的帮助文件的用户通常依赖于模块帮助主题的联机版本。 cmdlet 的 Online 参数在用户的默认 Internet 浏览器中打开 cmdlet 或高级函数帮助主题 Get-Help 的联机版本。

Get-Helpcmdlet 使用 cmdlet 或函数 的 HelpUri 属性的值来查找帮助主题的联机版本。

从 PowerShell 3.0 开始，可以通过在 cmdlet 类或 CmdletBinding 属性的 HelpUri 属性上定义 HelpUri 属性来帮助用户查找 cmdlet 和函数帮助主题的联机版本。 属性的值是 cmdlet 或函数 的 HelpUri 属性的值。

有关详细信息，请参阅 支持联机帮助。

另请参阅

写入 PowerShell 模块

支持可更新帮助

支持联机帮助