如何将语法添加到 cmdlet 帮助主题

注释

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

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

参数特性

必选
- 如果为 true，则参数必须出现在使用参数集的所有命令中。
- 如果为 false，则参数在使用参数集的所有命令中都是可选的。
位置
- 如果已命名，则需要参数名称。
- 如果位置，则参数名称是可选的。省略时，参数值必须位于命令中的指定位置。例如，如果值为 position=“1”，则参数值必须是命令中的第一个或仅未命名的参数值。
管道输入
- 如果为 true（ByValue），则可以通过管道将输入传递给参数。即使属性名称和对象类型与预期类型不匹配，输入也与参数（“bound to”）相关联。 PowerShell 参数绑定组件尝试将输入转换为正确的类型，并且仅在无法转换类型时才失败命令。参数集中只能由值关联一个参数。
- 如果为 true（ByPropertyName），则可以通过管道将输入传递给参数。但是，仅当参数名称与输入对象的属性名称匹配时，输入才会与参数相关联。例如，如果参数名称为 Path，则通过管道传递给 cmdlet 的对象仅在对象具有名为路径的属性时才与该参数相关联。
- 如果为 true（ByValue、ByPropertyName），则可以通过属性名称或值将输入管道传递给参数。参数集中只能由值关联一个参数。
- 如果为 false，则无法通过管道将输入传递给此参数。
高潮
- 如果为 true，则用户为参数值键入的文本可以包含通配符。
- 如果为 false，则用户为参数值键入的文本不能包含通配符。

参数值属性

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

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

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

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

收集语法信息

从 cmdlet 名称开始。
```
SYNTAX
    Get-Tech
```
列出 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 会在显示“帮助”主题时为你添加该信息。
添加参数值。在 PowerShell 中，参数值由其.NET类型表示。但是，可以缩写类型名称，例如 System.String 的“string”。
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
只要其含义明确，就缩写类型，例如 System.String 的字符串和 System.Int32 的字符串。

列出枚举的所有值，例如 -Type 上一示例中的参数，可将其设置为基本或高级。

[switch] 参数（如 -List 上一示例中）没有值。

将尖括号添加到占位符的参数值，与作为文本的参数值进行比较。

SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced

将可选参数及其 vales 括在方括号中。

SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

将可选参数名称（对于位置参数）括在方括号中。位置参数的名称（如以下示例中的 Name 参数）不必包含在命令中。
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
如果参数值可以包含多个值（如 Name 参数中的名称列表），请直接在参数值之后添加一对方括号。
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
如果用户可以从参数或参数值（如 Type 参数）中进行选择，请将选项括在大括号中，并使用排他 OR 符号（;)）。
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

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

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>

反馈

此页面是否有帮助？

Last updated on 2026-04-08