编写 PowerShell 模块的帮助

2025-10-02

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

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

模块帮助的类型

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

基于 XML 的帮助
- Cmdlet 帮助。描述模块中 cmdlet 的帮助主题是使用命令帮助架构的 XML 文件
- 提供程序帮助。描述模块中的提供程序的帮助主题是使用提供程序帮助架构的 XML 文件。
- 函数帮助。描述模块中函数的帮助主题可以是 XML 文件，这些文件使用函数中的命令帮助架构或基于注释的帮助主题，或者脚本或脚本模块
- 脚本帮助。描述模块中的脚本的帮助主题可以是使用脚本或脚本模块中命令帮助架构或基于注释的帮助主题的 XML 文件。
- 该 $PSHOME\Schemas\PSMaml 文件夹包含定义 XML 格式的架构文件。
概念性（“关于”）帮助文本文件

可以使用概念性（“about”）帮助主题来描述模块及其成员，并说明如何将成员一起使用来执行任务。默认情况下，PowerShell 包含以下 100 多个关于帮助主题的概念。文件名必须使用 about_<name>.help.txt 格式，例如 about_MyModule.help.txt。

注释

TOPIC节标头必须在文件第一行的第一列中开始。第二行的节内容应与文件名匹配，不 .help.txt 带后缀。必须完全缩进内容 4 个空格。第三行必须为空。 SYNOPSIS节标题必须在第四行的第一列中开始。必须在第五行中只缩进 4 个空格的内容。 cmdlet 必须 Get-Help 满足这些要求才能正确识别内容。
```
TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.
```
可以使用以下示例模板作为编写概念帮助主题的起点。除前两节外，概念帮助主题的结构是任意的。其余部分标题可以是适合你的内容的任何内容。
```
TOPIC
    about_<subject or module name>

SYNOPSIS
    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.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.
```
可以使用所需的任何样式和标记，但 PowerShell 将其视为纯文本，PowerShell 控制台中没有特殊呈现文本。以下建议可确保最佳显示结果和可读性。
- 将 UTF-8 与 BOM 编码配合使用，以确保任何特殊字符（多字节）字符都正确显示。
- 下划线节标题或使用所有大写字母来突出它们。这使得内容更易于扫描。
- 将每行的长度限制为 80 个字符。
- 缩进代码块和示例输出，以将它们与周围的散文分开。

模块帮助的位置

该 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 键的值中列出帮助主题文件，但帮助主题不受 cmdlet 的影响 Export-ModuleMember 。

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

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

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

支持可更新的帮助

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

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

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

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

支持联机帮助

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

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

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

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

另请参阅

反馈

此页面是否有帮助？