编写 PowerShell 脚本和函数的帮助

每当与他人共享 PowerShell 脚本和函数时，都应完整记录它们。 Get-Help cmdlet 以与显示 cmdlet 帮助相同的格式显示脚本和函数帮助主题，并且所有 Get-Help 参数都适用于脚本和函数帮助主题。

PowerShell 脚本可以包含有关脚本的帮助主题以及有关脚本中每个函数的帮助主题。独立于脚本共享的函数可以包含自己的帮助主题。

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

脚本和函数帮助的类型

基于评论的帮助

描述脚本或函数的帮助主题可以作为脚本或函数内的一组注释来实现。为脚本和脚本中的函数编写基于注释的帮助时，请特别注意放置基于注释的帮助的规则。放置位置确定 Get-Help cmdlet 是否将帮助主题与脚本或函数关联。有关编写基于注释的帮助主题的更多信息，请参阅 about_Comment_Based_Help。

基于 XML 的命令帮助

描述脚本或函数的帮助主题可以在使用命令帮助架构的 XML 文件中实现。要将脚本或函数与 XML 文件关联，请使用 ExternalHelp 注释关键字，后跟 XML 文件的路径和名称。

当 ExternalHelp 注释关键字存在时，即使 Get-Help 找不到与 ExternalHelp 的值匹配的帮助文件，它也优先于基于注释的帮助。ExternalHelp 关键字。

在线帮助

您可以将帮助主题发布到互联网上，然后直接 Get-Help 打开这些主题。有关编写基于注释的帮助主题的更多信息，请参阅支持联机帮助。

没有既定的方法来编写脚本和函数的概念（“关于”）主题。但是，您可以在 Internet 上发布概念性主题，在命令帮助主题的相关链接部分中列出主题及其 URL。

脚本和函数帮助的内容注意事项

• 如果您正在编写一个非常简短的帮助主题，其中仅包含几个可用的命令帮助部分，请务必包含脚本或函数参数的清晰描述。即使您决定省略示例描述，也要在示例部分中包含一两个示例命令。

• 在所有描述中，将该命令称为脚本或函数。此信息有助于用户理解和管理命令。

  例如，下面的详细描述表明New-Topic命令是一个脚本。这提醒用户运行时需要指定路径和全名。

  “New-Topic 脚本为输入文件中的每个主题名称创建一个空白概念主题...”

  以下详细描述表明 Disable-PSRemoting 是一个函数。当会话包含多个同名命令（其中一些命令可能被优先级较高的命令隐藏）时，此信息对用户特别有用。

  Disable-PSRemoting 函数禁用本地计算机上的所有会话配置...

• 在脚本帮助主题中，解释如何整体使用脚本。如果您还在为脚本中的函数编写帮助主题，请在脚本帮助主题中提及函数，并在脚本帮助主题的“相关链接”部分中包含对函数帮助主题的引用。相反，当函数是脚本的一部分时，请在函数帮助主题中解释该函数在脚本中扮演的角色以及如何独立使用它。然后在函数帮助主题的相关链接部分列出脚本帮助主题。

• 为脚本帮助主题编写示例时，请务必在示例命令中包含脚本文件的路径。这提醒用户必须显式指定路径，即使脚本位于当前目录中也是如此。

• 在函数帮助主题中，提醒用户该函数仅存在于当前会话中，要在其他会话中使用它，他们需要添加它，或者将其添加到 PowerShell 配置文件。

• 仅当脚本文件和帮助主题文件保存在正确的位置时，Get-Help 才显示脚本或函数的帮助主题。因此，在脚本或函数帮助主题中包含有关安装 PowerShell 或保存或安装脚本或函数的说明是没有用的。相反，请在用于分发脚本或函数的文档中包含任何安装说明。

参见

编写基于注释的帮助主题