支持联机帮助

项目
03/25/2025

注释

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

从 PowerShell 3.0 开始，有两种方法支持 PowerShell 命令的 Get-Help Online 功能。本主题介绍如何为不同的命令类型实现此功能。

关于联机帮助

联机帮助始终是 PowerShell 的重要组成部分。尽管 Get-Help cmdlet 在命令提示符处显示帮助主题，但许多用户更喜欢在线阅读体验，包括颜色编码、超链接以及社区内容和基于 wiki 的文档中共享想法。最重要的是，在“可更新帮助”出现之前，联机帮助提供了最 up-to日期版本的帮助文件。

随着 PowerShell 3.0 中可更新帮助的出现，联机帮助仍起着重要作用。除了灵活的用户体验之外，联机帮助还为不使用或无法使用“可更新帮助”来下载帮助主题的用户提供帮助。

Get-Help -Online 的工作原理

为了帮助用户找到命令的联机帮助主题，Get-Help 命令具有一个 Online 参数，该参数为用户的默认 Internet 浏览器中的命令打开联机版本的帮助主题。

例如，以下命令将打开 Invoke-Command cmdlet 的联机帮助主题。

Get-Help Invoke-Command -Online

若要实现 Get-Help -Online，Get-Help cmdlet 会在以下位置查找联机版本帮助主题的统一资源标识符（URI）。

命令帮助主题的 相关链接 部分中的第一个链接。帮助主题必须安装在用户的计算机上。此功能已在 PowerShell 2.0 中引入。
任何命令的 HelpUri 属性。即使用户计算机上未安装命令的帮助主题，也可以访问 HelpUri 属性。此功能已在 PowerShell 3.0 中引入。

在获取 HelpUri 属性值之前，Get-Help 查找 相关链接 部分中第一个条目中的 URI。如果属性值不正确或已更改，则可以通过在第一个相关链接中输入其他值来替代该值。但是，第一个相关链接仅在用户计算机上安装帮助主题时才有效。

可以通过为命令的基于 XML 的帮助主题的 相关链接 部分中的第一个条目添加有效的 URI 来支持任何命令的 Get-Help -Online。此选项仅在基于 XML 的帮助主题中有效，仅在用户计算机上安装帮助主题时才有效。安装帮助主题并填充 URI 时，此值优先于命令的 HelpUri 属性。

若要支持此功能，URI 必须出现在 maml:relatedLinks 元素中第一个 maml:relatedLinks/maml:navigationLink 元素下的 maml:uri 元素中。

以下 XML 显示了 URI 的正确位置。 maml:linkText 元素中的 Online version: 文本是最佳做法，但这不是必需的。

<maml:relatedLinks>
    <maml:navigationLink>
        <maml:linkText>Online version:</maml:linkText>
        <maml:uri>https://go.microsoft.com/fwlink/?LinkID=113279</maml:uri>
    </maml:navigationLink>
    <maml:navigationLink>
        <maml:linkText>about_History</maml:linkText>
        <maml:uri/>
    </maml:navigationLink>
</maml:relatedLinks>

将 HelpUri 属性添加到命令

本部分演示如何将 HelpUri 属性添加到不同类型的命令。

将 HelpUri 属性添加到 Cmdlet

对于用 C# 编写的 cmdlet，请将 HelpUri 属性添加到 Cmdlet 类。特性的值必须是以 http 或 https开头的 URI。

以下代码显示了 Get-History cmdlet 类的 HelpUri 属性。

[Cmdlet(VerbsCommon.Get, "History", HelpUri = "https://go.microsoft.com/fwlink/?LinkID=001122")]

将 HelpUri 属性添加到高级函数

对于高级函数，请将 HelpUri 属性添加到 CmdletBinding 属性。该属性的值必须是以“http”或“https”开头的 URI。

以下代码显示了 New-Calendar 函数的 HelpUri 属性

function New-Calendar {
    [CmdletBinding(SupportsShouldProcess=$true,
    HelpUri="https://go.microsoft.com/fwlink/?LinkID=01122")]

将 HelpUri 属性添加到 cim 命令

对于 CIM 命令，请将 HelpUri 属性添加到 CDXML 文件中的 CmdletMetadata 元素。特性的值必须是以 http 或 https开头的 URI。

以下代码显示了 Start-Debug CIM 命令的 HelpUri 属性

<CmdletMetadata Verb="Debug" HelpUri="https://go.microsoft.com/fwlink/?LinkID=001122"/>

将 HelpUri 属性添加到工作流

对于使用 PowerShell 语言编写的工作流，请将 .EXTERNALHELP 注释关键字添加到工作流代码。关键字的值必须是以 http 或 https开头的 URI。

注释

PowerShell 中基于 XAML 的工作流不支持 HelpUri 属性。

以下代码显示了工作流文件中的 .EXTERNALHELP 关键字。

# .EXTERNALHELP "https://go.microsoft.com/fwlink/?LinkID=138338"

通过