通过

支持联机帮助

  • 项目

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

关于联机帮助

联机帮助一直是 PowerShell 的重要组成部分。 尽管 cmdlet 在命令提示符下显示帮助主题，但许多用户更喜欢在线阅读体验，包括颜色编码、超链接和共享 Community 内容和基于 wiki 的文档。 Get-Help 最重要的是，在可更新帮助出现之前，联机帮助提供了最新版本的帮助文件。

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

Get-Help -Online 的工作原理

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

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

Get-Help Invoke-Command -Online

若要实现 ，cmdlet 将查找以下位置 (联机版本帮助主题) 统一资源标识符 Get-Help -Online Get-Help 和 URI。

  • 命令的帮助主题 的"相关链接 "部分的第一个链接。 帮助主题必须安装在用户的计算机上。 PowerShell 2.0 中引入了此功能。

  • 任何 命令的 HelpUri 属性。 即使用户计算机上未安装命令的帮助主题，也可访问 HelpUri 属性。 PowerShell 3.0 中引入了此功能。

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

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

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

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

<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。

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

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

将 HelpUri 属性添加到高级函数

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

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

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

将 HelpUri 属性添加到 CIM 命令

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

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

<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"