可更新的帮助创作 - 分步

本文记录了发布可更新帮助所需的步骤。

创作可更新帮助：分步

可更新的帮助是为最终用户设计的，但它也为模块作者和帮助编写者提供了显着的好处，包括在模块发布后很长时间内添加内容、修复错误、以多种 UI 文化交付以及响应用户评论和请求的能力已发货。本主题介绍如何打包和上传帮助文件，以便用户可以使用 Update-Help 和 Save-Help cmdlet 下载并安装它们。

以下步骤概述了支持可更新帮助的过程。

第 1 步：查找帮助文件的 Internet 站点

创建可更新帮助的第一步是找到模块帮助文件的 Internet 位置。实际上，您可以使用两个不同的位置。您可以将模块的帮助信息文件（HelpInfo XML - 如下所述）保存在一个 Internet 位置，并将帮助内容文件（CAB 和 ZIP）保存在另一 Internet 位置。模块的所有帮助内容文件必须位于同一位置。您可以将不同模块的帮助内容文件放在同一位置。

步骤 2：将 HelpInfoURI 键添加到模块清单中

将 HelpInfoURI 键添加到您的模块清单中。键的值是模块的 HelpInfo XML 信息文件位置的统一资源标识符 (URI)。为了安全起见，地址必须以 http: 或 https: 开头。 URI 应指定 HelpInfo XML 文件的 Internet 位置。不要包含 HelpInfo XML 文件名。

例如：

@{
    RootModule = TestModule.psm1
    ModuleVersion = '2.0'
    HelpInfoURI = 'https://go.microsoft.com/fwlink/?LinkID=0123'
}

笔记

HelpInfoURI 必须以正斜杠 (/) 字符结尾，或重定向到以正斜杠 (/) 结尾的位置。

步骤 3：创建 HelpInfo XML 文件

HelpInfo XML 信息文件包含帮助文件的 Internet 位置的 URI 以及模块在每种受支持的 UI 区域性中的最新帮助文件的版本号。每个 PowerShell 模块都有一个 HelpInfo XML 文件。更新帮助文件时，必须更新 HelpInfo XML 文件。有关详细信息，请参阅如何创建 HelpInfo XML 文件。

步骤 4：创建 CAB 和 ZIP 文件

Windows 上的 PowerShell 期望模块的帮助内容文件存储在 CAB 文件中。 Linux 或 macOS 上的 PowerShell 希望模块的帮助内容文件存储在 ZIP 文件中。如果您的模块跨多个平台运行，则必须创建两种格式。

使用工具（例如 MakeCab.exe）创建包含模块帮助文件的 CAB 文件。为每个受支持的 UI 区域性中的帮助文件创建单独的 CAB 文件。有关详细信息，请参阅如何准备可更新的帮助 CAB 文件。

您可以使用 Compress-Archive cmdlet 创建 ZIP 文件。

第 5 步：上传您的文件

要发布新的或更新的帮助文件，请将帮助内容文件上传到 HelpInfo XML 文件中 HelpContentUri 元素指定的 Internet 位置。然后，将 HelpInfo XML 文件上传到模块清单中 HelpInfoUri 键值指定的 Internet 位置。

使用 PlatyPS 创建帮助内容

PlatyPS 是一个 PowerShell 模块，旨在帮助您为模块创建帮助内容。您在 Markdown 文件中创作帮助内容。 PlatyPS 可以为您的 cmdlet 创建 Markdown 模板、将 Markdown 文件转换为 XML 帮助格式 (MAML)、创建 HelpInfo XML 文件，并将 MAML 帮助内容打包到 CAB 和 ZIP 文件中。

有关详细信息，请参阅使用 PlatyPS 创建基于 XML 的帮助。