支持在线帮助

笔记

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

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

关于在线帮助

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

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

在线获取帮助的工作原理

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

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

Get-Help Invoke-Command -Online

为了实现 Get-Help -Online，Get-Help cmdlet 在以下位置查找在线版本帮助主题的统一资源标识符 (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"