如何创建 cmdlet 帮助文件

笔记

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

本部分介绍如何创建包含 Windows PowerShell cmdlet 帮助主题内容的有效 XML 文件。本节讨论如何命名帮助文件、如何添加适当的 XML 标头以及如何添加将包含 cmdlet 帮助内容的不同部分的节点。

笔记

要完整查看帮助文件，请打开位于 Windows PowerShell 安装目录中的 dll-Help.xml 文件之一。例如，Microsoft.PowerShell.Commands.Management.dll-Help.xml 文件包含多个 PowerShell cmdlet 的内容。

如何创建 cmdlet 帮助文件

1. 创建一个文本文件并使用 UTF8 编码保存。文件名必须具有以下格式，以便 Windows PowerShell 可以将其检测为 cmdlet 帮助文件。

   <PSSnapInAssemblyName>.dll-Help.xml

2. 将以下 XML 标头添加到文本文件中。请注意，该文件将根据 Microsoft 辅助标记语言 (MAML) 架构进行验证。目前，PowerShell 不提供任何工具来验证该文件。

   <?xml version="1.0" encoding="utf-8" ?> <helpItems xmlns="http://msh" schema="maml">

3. 将 Command 节点添加到程序集中每个 cmdlet 的 cmdlet 帮助文件中。 命令 节点中的每个节点都与 cmdlet 帮助主题的不同部分相关。

   下表列出了每个节点的 XML 元素，后跟每个节点的描述。

   <details>

   添加 cmdlet 帮助主题的 NAME 和 SYNOPSIS 部分的内容。有关详细信息，请参阅如何添加 Cmdlet 名称和概要。

   <maml:description>

   添加 cmdlet 帮助主题的描述部分的内容。有关详细信息，请参阅如何将详细说明添加到 Cmdlet 帮助主题。

   <command:syntax>

   添加 cmdlet 帮助主题的语法部分的内容。有关详细信息，请参阅如何将语法添加到 Cmdlet 帮助主题。

   <command:parameters>

   添加 cmdlet 帮助主题的 PARAMETERS 部分的内容。有关详细信息，请参阅如何向 Cmdlet 帮助主题添加参数。

   <command:inputTypes>

   添加 cmdlet 帮助主题的 INPUTS 部分的内容。有关详细信息，请参阅如何将输入类型添加到 Cmdlet 帮助主题。

   <command:returnValues>

   添加 cmdlet 帮助主题的 OUTPUTS 部分的内容。有关详细信息，请参阅如何将返回值添加到 Cmdlet 帮助主题。

   <maml:alertset>

   添加 cmdlet 帮助主题的“NOTES”部分的内容。有关详细信息，请参阅如何向 Cmdlet 帮助主题添加注释。

   <command:examples>

   添加 cmdlet 帮助主题的示例部分的内容。有关详细信息，请参阅如何向 Cmdlet 帮助主题添加示例。

   <maml:relatedLinks>

   添加 cmdlet 帮助主题的相关链接部分的内容。有关详细信息，请参阅如何将相关链接添加到 Cmdlet 帮助主题。

例子

下面是一个命令节点示例，其中包含 cmdlet 帮助主题各个部分的节点。

<command:command
  xmlns:maml="http://schemas.microsoft.com/maml/2004/10"
  xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10"
  xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
  <command:details>
    <!--Add name and synopsis here-->
  </command:details>
  <maml:description>
    <!--Add detailed description here-->
  </maml:description>
  <command:syntax>
    <!--Add syntax information here-->
  </command:syntax>
  <command:parameters>
    <!--Add parameter information here-->
  </command:parameters>
  <command:inputTypes>
    <!--Add input type information here-->
  </command:inputTypes>
  <command:returnValues>
    <!--Add return value information here-->
  </command:returnValues>
  <maml:alertSet>
    <!--Add Note information here-->
  </maml:alertSet>
  <command:examples>
    <!--Add cmdlet examples here-->
  </command:examples>
  <maml:relatedLinks>
    <!--Add links to related content here-->
  </maml:relatedLinks>
</command:command>

参见

• 如何添加 Cmdlet 名称和概要
• 如何向 Cmdlet 帮助主题添加详细说明
• 如何向 Cmdlet 帮助主题添加语法
• 如何向 Cmdlet 帮助主题添加参数
• 如何将输入类型添加到 Cmdlet 帮助主题
• 如何将返回值添加到 Cmdlet 帮助主题
• 如何向 Cmdlet 帮助主题添加注释
• 如何向 Cmdlet 帮助主题添加示例
• 如何将相关链接添加到 Cmdlet 帮助主题
• Windows PowerShell SDK