使用 PlatyPS 创建基于 XML 的帮助

创建 PowerShell 模块时，始终建议您包含所创建的 cmdlet 的详细帮助。如果您的 cmdlet 是在编译代码中实现的，则必须使用基于 XML 的帮助。这种 XML 格式称为 Microsoft 辅助标记语言 (MAML)。

旧版 PowerShell SDK 文档涵盖了为打包到模块中的 PowerShell cmdlet 创建帮助的详细信息。但是，PowerShell 不提供任何用于创建基于 XML 的帮助的工具。 SDK 文档解释了 MAML 帮助的结构，但让您需要手动创建复杂且深度嵌套的 MAML 内容。

这就是 PlatyPS 模块可以提供帮助的地方。

什么是 PlatyPS？

PlatyPS 是一个开源工具，最初是一个黑客马拉松项目，旨在简化 MAML 的创建和维护。 PlatyPS 记录了模块中每个 cmdlet 的参数集语法和各个参数。 PlatyPS 创建包含语法信息的结构化 Markdown 文件。它无法创建描述或提供示例。

PlatyPS 创建占位符供您填写描述和示例。添加所需信息后，PlatyPS 将 Markdown 文件编译为 MAML 文件。 PowerShell 的帮助系统还允许纯文本概念帮助文件（关于主题）。 PlatyPS 有一个 cmdlet 可以为新的 about 文件创建结构化 Markdown 模板，但这些 about_*.help.txt 文件必须手动维护。

您可以在模块中包含 MAML 和文本帮助文件。您还可以使用 PlatyPS 将帮助文件编译到可托管的 CAB 包中以获取可更新的帮助。

开始使用 PlatyPS

首先，您必须从 PowerShell Gallery 安装 PlatyPS。

# Install using PowerShellGet 2.x
Install-Module platyps -Force

# Install using PSResourceGet 1.x
Install-PSResource platyps -Reinstall

安装 PlatyPS 后，将该模块导入到您的会话中。

Import-Module platyps

以下流程图概述了创建或更新 PowerShell 参考内容的过程。

为 PowerShell 模块创建 Markdown 内容

1. 将新模块导入到会话中。对需要记录的每个模块重复此步骤。

   运行以下命令导入模块：

   Import-Module <your module name>
   

2. 使用 PlatyPS 为模块页面以及模块内所有关联的 cmdlet 生成 Markdown 文件。对需要记录的每个模块重复此步骤。

   $OutputFolder = <output path>
   $parameters = @{
       Module = <ModuleName>
       OutputFolder = $OutputFolder
       AlphabeticParamsOrder = $true
       WithModulePage = $true
       ExcludeDontShow = $true
       Encoding = [System.Text.Encoding]::UTF8
   }
   New-MarkdownHelp @parameters
   
   New-MarkdownAboutHelp -OutputFolder $OutputFolder -AboutName "topic_name"
   

   如果输出文件夹不存在，New-MarkdownHelp 将创建它。在此示例中，New-MarkdownHelp 为模块中的每个 cmdlet 创建一个 Markdown 文件。它还在名为 <ModuleName>.md 的文件中创建模块页面。此模块页面包含模块中包含的 cmdlet 列表以及概要描述的占位符。模块页面中的元数据来自模块清单，PlatyPS 使用它来创建 HelpInfo XML 文件（如下所述）。

   New-MarkdownAboutHelp 创建一个名为 about_topic_name.md 的新 about 文件。

   有关更多信息，请参阅 New-MarkdownHelp 和 New-MarkdownAboutHelp。

当模块更改时更新现有 Markdown 内容

PlatyPS 还可以更新模块的现有 Markdown 文件。使用此步骤更新具有新 cmdlet、新参数或已更改参数的现有模块。

1. 将新模块导入到会话中。对需要记录的每个模块重复此步骤。

   运行以下命令导入模块：

   Import-Module <your module name>
   

2. 使用 PlatyPS 更新模块登录页面以及模块内所有关联 cmdlet 的 Markdown 文件。对需要记录的每个模块重复此步骤。

   $parameters = @{
       Path = <folder with Markdown>
       RefreshModulePage = $true
       AlphabeticParamsOrder = $true
       UpdateInputOutput = $true
       ExcludeDontShow = $true
       LogPath = <path to store log file>
       Encoding = [System.Text.Encoding]::UTF8
   }
   Update-MarkdownHelpModule @parameters
   

   Update-MarkdownHelpModule 更新指定文件夹中的 cmdlet 和模块 Markdown 文件。它不会更新 about_*.md 文件。模块文件 (ModuleName.md) 接收已添加到 cmdlet 文件中的任何新概要文本。对 cmdlet 文件的更新包括以下更改：

   • 新参数集
3. 新参数
4. 更新了参数元数据
5. 更新了输入和输出类型信息

有关更多信息，请参阅 Update-MarkdownHelpModule。

编辑新的或更新的 Markdown 文件

PlatyPS 记录了参数集和各个参数的语法。它无法创建描述或提供示例。需要内容的特定区域包含在花括号中。例如：{{填写描述}}

您需要添加概要、cmdlet 描述、每个参数的描述以及至少一个示例。

有关编写 PowerShell 内容的详细信息，请参阅以下文章：

• PowerShell 风格指南
• 编辑参考文章

笔记

PlatyPS 有一个用于 cmdlet 参考的特定架构。该架构仅允许文档特定部分中的某些 Markdown 块。如果您将内容放在错误的位置，PlatyPS 构建步骤将失败。有关更多信息，请参阅 PlatyPS 存储库中的架构文档。有关格式正确的 cmdlet 参考的完整示例，请参阅 Get-Item。

为每个 cmdlet 提供所需的内容后，您需要确保更新模块登录页面。验证您的模块在 <module-name>.md 文件的 YAML 元数据中具有正确的Module Guid 和下载帮助链接 值。添加任何缺失的元数据。

此外，您可能会注意到某些 cmdlet 可能缺少概要（简短描述）。以下命令使用您的概要描述文本更新模块登录页面。打开模块登陆页面以验证描述。

Update-MarkdownHelpModule -Path <full path output folder> -RefreshModulePage

现在您已输入所有内容，您可以创建由 PowerShell 控制台中的 Get-Help 显示的 MAML 帮助文件。

创建外部帮助文件

此步骤将创建由 PowerShell 控制台中的 Get-Help 显示的 MAML 帮助文件。

要构建 MAML 文件，请运行以下命令：

New-ExternalHelp -Path <folder with MDs> -OutputPath <output help folder>

New-ExternalHelp 将所有 cmdlet Markdown 文件转换为一个（或多个）MAML 文件。关于文件将转换为具有以下名称格式的纯文本文件：about_topic_name.help.txt。 Markdown 内容必须满足 PlatyPS 架构的要求。当内容不遵循架构时，New-ExternalHelp 会退出并出现错误。您必须编辑文件以修复架构违规。

警告

PlatyPS 将 about_*.md 文件转换为纯文本的效果很差。您必须使用非常简单的 Markdown 才能获得可接受的结果。您可能希望以纯文本 about_topic_name.help.txt 格式维护文件，而不是允许 PlatyPS 对其进行转换。

完成此步骤后，您将在目标输出文件夹中看到 *-help.xml 和 about_*.help.txt 文件。

有关详细信息，请参阅 New-ExternalHelp

测试编译后的帮助文件

您可以使用 Get-HelpPreview cmdlet 验证内容：

Get-HelpPreview -Path "<ModuleName>-Help.xml"

该 cmdlet 读取已编译的 MAML 文件并以您从 Get-Help 收到的相同格式输出内容。这允许您检查结果以验证 Markdown 文件是否正确编译并产生所需的结果。如果发现错误，请重新编辑 Markdown 文件并重新编译 MAML。

现在您可以发布帮助文件了。

发布您的帮助

现在您已将 Markdown 文件编译成 PowerShell 帮助文件，您可以将这些文件提供给用户了。有两个选项可在 PowerShell 控制台中提供帮助。

• 将帮助文件与模块打包
• 创建用户使用 Update-Help cmdlet 安装的可更新帮助包

模块的打包帮助

帮助文件可以与您的模块打包在一起。有关文件夹结构的详细信息，请参阅编写模块帮助。您应该将帮助文件列表包含在模块清单中 FileList 键的值中。

创建可更新的帮助包

概括地说，创建可更新帮助的步骤包括：

1. 查找一个网站来托管您的帮助文件
2. 将 HelpInfoURI 键添加到您的模块清单中
3. 创建帮助信息 XML 文件
4. 创建CAB文件
5. 上传您的文件

有关详细信息，请参阅支持可更新帮助：分步。

PlatyPS 可帮助您完成其中一些步骤。

HelpInfoURI 是一个 URL，指向您的帮助文件在 Internet 上的托管位置。该值在模块清单中配置。 Update-Help 读取模块清单以获取此 URL 并下载可更新的帮助内容。此 URL 应仅指向文件夹位置，而不应指向单个文件。 Update-Help 根据模块清单和 HelpInfo XML 文件中的其他信息构造要下载的文件名。

这很重要

HelpInfoURI 必须以正斜杠字符 (/) 结尾。如果没有该字符，Update-Help 就无法构建正确的文件路径来下载内容。此外，大多数基于 HTTP 的文件服务都区分大小写。 HelpInfo XML 文件中的模块元数据包含正确的字母大小写非常重要。

New-ExternalHelp cmdlet 在输出文件夹中创建 HelpInfo XML 文件。 HelpInfo XML 文件是使用模块 Markdown 文件 (ModuleName.md) 中包含的 YAML 元数据构建的。

New-ExternalHelpCab cmdlet 创建包含您编译的 MAML 和 about_*.help.txt 文件的 ZIP 和 CAB 文件。 CAB 文件与所有版本的 PowerShell 兼容。 PowerShell 6 及更高版本可以使用 ZIP 文件。

$helpCabParameters = @{
    CabFilesFolder = $MamlOutputFolder
    LandingPagePath = $LandingPage
    OutputFolder = $CabOutputFolder
}
New-ExternalHelpCab @helpCabParameters

创建 ZIP 和 CAB 文件后，将 ZIP、CAB 和 HelpInfo XML 文件上传到 HTTP 文件服务器。将文件放在 HelpInfoURI 指示的位置。

有关详细信息，请参阅New-ExternalHelpCab。

其他发布选项

Markdown 是一种多功能格式，可以轻松转换为其他发布格式。使用 Pandoc 等工具，您可以将 Markdown 帮助文件转换为许多不同的文档格式，包括纯文本、HTML、PDF 和 Office 文档格式。

此外，PowerShell 6 及更高版本中的 cmdlet ConvertFrom-Markdown 和 Show-Markdown 可用于将 Markdown 转换为 HTML 或在 PowerShell 控制台中创建彩色显示。

已知问题

PlatyPS 对它创建和编译的 Markdown 文件的结构模式非常敏感。编写违反此模式的有效 Markdown 非常容易。有关详细信息，请参阅 PowerShell 样式指南和编辑参考文章。