编写 PowerShell 模块的帮助

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

本文档解释了模块帮助主题的格式和正确位置，并提出了模块帮助内容的指南。

模块帮助的类型

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

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

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

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

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

• 概念（“关于”）帮助。您可以使用概念性（“关于”）帮助主题来描述模块及其成员，并解释如何一起使用这些成员来执行任务。概念帮助主题是采用 Unicode (UTF-8) 编码的文本文件。文件名必须使用 about_.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 can't work in the PowerShell console.
  
  

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

模块帮助的放置

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

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

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

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

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

支持可更新的帮助

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

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

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

有关可更新帮助的详细信息，请参阅支持可更新帮助。

支持在线帮助

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

Get-Help cmdlet 使用 cmdlet 或函数的 HelpUri 属性的值来查找帮助主题的在线版本。

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

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

参见

• 编写 PowerShell 模块
• 支持可更新的帮助
• 支持在线帮助