如何向 cmdlet 帮助主题添加语法

笔记

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

在开始为 cmdlet 帮助文件中的语法图编写 XML 之前，请阅读本节以清楚地了解需要提供的数据类型，例如参数属性以及该数据在语法中的显示方式图表..

参数属性

• 必需的

  • 如果为 true，则该参数必须出现在使用该参数集的所有命令中。
• 如果为 false，则该参数在使用该参数集的所有命令中都是可选的。

参数值属性

• 必需的

  • 如果为 true，则每当在命令中使用参数时都必须使用指定的值。
• 如果为 false，则参数值是可选的。通常，仅当某个值是参数的多个有效值之一时（例如枚举类型），该值才是可选的。

参数值的 Required 属性与参数的 Required 属性不同。

参数的 required 属性指示在调用 cmdlet 时是否必须包含该参数（及其值）。相反，仅当参数包含在命令中时才使用参数值的必需属性。它指示该特定值是否必须与参数一起使用。

通常，占位符参数值是必需的，而文字参数值则不是必需的，因为它们是可能与参数一起使用的多个值之一。

收集语法信息

1. 以 cmdlet 名称开头。

   SYNTAX
       Get-Tech
   

2. 列出 cmdlet 的所有参数。在每个参数名称前键入连字符 (-)。将参数分成参数集（某些 cmdlet 可能只有一个参数集）。在此示例中，Get-Tech cmdlet 有两个参数集。

   SYNTAX
       Get-Tech -name -type
       Get-Tech -ID -list -type
   

   使用 cmdlet 名称启动每个参数集。

   首先列出默认参数集。默认参数由 cmdlet 类指定。

   对于每个参数集，首先列出其唯一参数，除非有必须首先出现的位置参数。在上一示例中，Name 和 ID 参数是两个参数集的唯一参数（每个参数集必须有一个该参数集唯一的参数）。这使得用户更容易确定他们需要为参数集提供哪些参数。

   按照参数在命令中出现的顺序列出参数。如果顺序不重要，请将相关参数放在一起，或者先列出最常用的参数。

   如果 cmdlet 支持 ShouldProcess，请务必列出WhatIf 和Confirm 参数。

   不要在语法图中列出常用参数（例如 Verbose、Debug 和 ErrorAction）。 Get-Help cmdlet 在显示帮助主题时会为您添加该信息。

3. 添加参数值。在 PowerShell 中，参数值由其 .NET 类型表示。但是，类型名称可以缩写，例如 System.String 的“string”。

   SYNTAX
       Get-Tech -name string -type basic advanced
       Get-Tech -ID int -list -type basic advanced
   

   只要含义明确，就使用缩写类型，例如 string 表示 System.String，int 表示 System.Int32 >。

   列出枚举的所有值，例如上例中的-type参数，可以设置为basic或advanced。

   开关参数（例如上例中的 -list）没有值。

4. 与作为文字的参数值相比，向作为占位符的参数值添加尖括号。

   SYNTAX
       Get-Tech -name <string> -type basic advanced
       Get-Tech -ID <int> -list -type basic advanced
   

5. 将可选参数及其值括在方括号中。

   SYNTAX
       Get-Tech -name <string> [-type basic advanced]
       Get-Tech -ID <int> [-list] [-type basic advanced]
   

6. 将可选参数名称（对于位置参数）括在方括号中。位置参数的名称（例如以下示例中的 Name 参数）不必包含在命令中。

   SYNTAX
       Get-Tech [-name] <string> [-type basic advanced]
       Get-Tech -ID <int> [-list] [-type basic advanced]
   

7. 如果参数值可以包含多个值（例如 Name 参数中的名称列表），请直接在参数值后面添加一对方括号。

   SYNTAX
       Get-Tech [-name] <string[]> [-type basic advanced]
       Get-Tech -ID <int[]> [-list] [-type basic advanced]
   

8. 如果用户可以从参数或参数值（例如 Type 参数）中进行选择，请将选项括在大括号中，并用异或符号 (;) 分隔它们。

   SYNTAX
       Get-Tech [-name] <string[]> [-type {basic | advanced}]
       Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
   

9. 如果参数值必须使用特定格式（例如引号或括号），请在语法中显示格式。

   SYNTAX
       Get-Tech [-name] <"string[]"> [-type {basic | advanced}]
       Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
   

对语法图 XML 进行编码

XML 的语法节点紧接在描述节点之后开始，以 </maml:description> 标记结束。有关收集语法图中使用的数据的信息，请参阅收集语法信息。

添加语法节点

cmdlet 帮助主题中显示的语法图是根据 XML 语法节点中的数据生成的。语法节点包含在一对 <command:syntax> 标记中。 cmdlet 的每个参数集都包含在一对 <command:syntaxitem> 标记中。您可以添加的 <command:syntaxitem> 标记的数量没有限制。

以下示例显示了一个语法节点，该节点具有两个参数集的语法项节点。

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

将 cmdlet 名称添加到参数集数据

cmdlet 的每个参数集在语法项节点中指定。每个语法项节点都以一对包含 cmdlet 名称的 <maml:name> 标记开头。

以下示例包括一个语法节点，该节点具有两个参数集的语法项节点。

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

添加参数

添加到语法项节点的每个参数都在一对 <command:parameter> 标记内指定。参数集中包含的每个参数都需要一对 <command:parameter> 标记，PowerShell 提供的常用参数除外。

开始 <command:parameter> 标记的属性决定参数在语法图中的显示方式。有关参数属性的信息，请参阅参数属性。

笔记

<command:parameter> 标记支持其内容从不显示的子元素 <maml:description>。参数描述在XML的参数节点中指定。为了避免语法项 bodes 和参数节点中的信息不一致，请省略 (<maml:description> 或将其留空。

以下示例包括具有两个参数的参数集的语法项节点。

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>