使用 PlatyPS 创建基于 XML 的帮助

2024-12-12

创建 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，用于为有关文件的新创建结构化 Markdown 模板，但必须手动维护这些文件。

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

开始使用 PlatyPS

首先，必须从 PowerShell 库安装 PlatyPS。

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

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

安装 PlatyPS 后，将模块导入会话。

Import-Module platyps

以程图概述了创建或更新 PowerShell 引用内容的过程。

使用 PlatyPS 创建基于 XML 的帮助的工作流

为 PowerShell 模块创建 Markdown 内容

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

运行以下命令以导入模块：
```
Import-Module <your module name>
```
使用 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 列表，以及 Synopsis 说明的占位符。模块页中的元数据来自模块清单，PlatyPS 使用该文件创建 HelpInfo XML 文件（如下面的所述）。

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

有关详细信息，请参阅 New-MarkdownHelp 和 New-MarkdownAboutHelp。

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

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

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

运行以下命令以导入模块：
```
Import-Module <your module name>
```
使用 PlatyPS 更新模块登陆页的 Markdown 文件以及模块中的所有关联 cmdlet。对需要记录的每个模块重复此步骤。
```
$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 文件的任何新 Synopsis 文本。对 cmdlet 文件的更新包括以下更改：
- 新参数集
- 新参数
- 更新了参数元数据
- 更新了输入和输出类型信息
有关详细信息，请参阅 Update-MarkdownHelpModule。

编辑新的或更新的 Markdown 文件

PlatyPS 记录参数集和各个参数的语法。它无法创建说明或提供示例。需要内容的特定区域包含在大括号中。例如：{{ Fill in the Description }}

Markdown 模板，其中显示了 VS Code 中的占位符

需要添加一个摘要、cmdlet 的说明、每个参数的说明以及至少一个示例。

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

注意

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

为每个 cmdlet 提供所需的内容后，需要确保更新模块登陆页。验证模块是否在 <module-name>.md 文件的 YAML 元数据中具有正确的 Module Guid 和 Download Help Link 值。添加任何缺失的元数据。

此外，你可能会注意到，某些 cmdlet 可能缺少 Synopsis（简短说明）。以下命令使用 Synopsis 说明文本更新模块登陆页。打开模块登陆页以验证说明。

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 键的值中包含帮助文件列表。

创建可更新的帮助包

概括而言，创建可更新帮助的步骤包括：

查找用于托管帮助文件的 Internet 站点
将 HelpInfoURI 密钥添加到模块清单
创建 HelpInfo XML 文件
创建 CAB 文件
上传文件

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

PlatyPS 会帮助你执行其中一些步骤。

HelpInfoURI 是指向帮助文件托管在 Internet 上的位置的 URL。此值在模块清单中配置。 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 创建 ZIP 和 CAB 文件，其中包含已编译的 MAML 和 about_*.help.txt 文件。 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 文档格式。

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

已知问题

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

通过