如何将示例添加到 cmdlet 帮助主题

笔记

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

有关 cmdlet 帮助中的示例的须知事项

• 列出命令中的所有参数名称，即使参数名称是可选的。这有助于用户轻松解释命令。

• 避免使用别名和部分参数名称，即使它们在 PowerShell 中工作。

• 在示例描述中，解释该命令构造的合理性。解释为什么选择特定参数和值，以及如何使用变量。

• 如果命令使用表达式，请详细解释它们。

• 如果命令使用对象的属性和方法，尤其是默认显示中未出现的属性，请使用示例作为向用户介绍该对象的机会。

显示示例的帮助视图

示例仅显示在 cmdlet 帮助的详细视图和完整视图中。

添加示例节点

以下 XML 显示如何添加包含单个 Example 节点的 Examples 节点。为要包含在主题中的每个示例添加其他示例节点。

<command:examples>
  <command:example>
  </command:example>
</command:examples>

添加示例标题

以下 XML 显示如何为示例添加标题。 标题用于将该示例与其他示例区分开来。 PowerShell 使用包含连续示例编号的标准标头。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
  </command:example>
</command:examples>

添加前面的字符

以下 XML 显示如何添加紧邻示例命令之前显示的字符（例如 Windows PowerShell 提示符）（中间没有任何空格）。 PowerShell 使用 Windows PowerShell 提示符：C:\PS>。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:introduction>
      <maml:para>C:\PS></maml:para>
    </maml:introduction>
</command:example>
</command:examples>

添加命令

以下 XML 显示了如何添加示例的实际命令。添加命令时，键入 cmdlet 和参数的完整名称（不要使用别名）。另外，请尽可能使用小写字符。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:introduction>
      <maml:para>C:\PS></maml:para>
    </maml:introduction>
    <dev:code> command </dev:code>
</command:example>
</command:examples>

添加描述

以下 XML 显示了如何添加示例的描述。尽管可以使用多个 <maml:para> 标记，但 PowerShell 使用一组 <maml:para> 标记进行描述。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:introduction>
      <maml:para>C:\PS></maml:para>
    </maml:introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
    </dev:remarks>
</command:example>
</command:examples>

添加示例输出

以下 XML 显示如何添加命令的输出。命令结果信息是可选的，但在某些情况下，它有助于演示使用特定参数的效果。 PowerShell 使用两组空白 <maml:para> 标记将命令输出与命令分开。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:introduction>
      <maml:para>C:\PS></maml:para>
    </maml:introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
      <maml:para></maml:para>
      <maml:para></maml:para>
      <maml:para> command output </maml:para>
</dev:remarks>
</command:example>
</command:examples>