如何添加参数信息

笔记

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

本部分介绍如何添加 cmdlet 帮助主题的参数部分中显示的内容。帮助主题的参数部分列出了 cmdlet 的每个参数，并提供每个参数的详细说明。

PARAMETERS 部分的内容应与帮助主题的SYNTAX 部分的内容一致。帮助作者有责任确保语法 和参数 节点包含相似的XML 元素。

笔记

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

添加参数

1. 打开 cmdlet 帮助文件并找到您正在记录的 cmdlet 的命令节点。如果您要添加新的 cmdlet，则需要创建新的 Command 节点。您的帮助文件将包含您为其提供帮助内容的每个 cmdlet 的命令节点。以下是空白 Command 节点的示例。

   <command:command>
   </command:command>
   

2. 在命令节点中，找到描述节点并添加参数节点，如下所示。只允许有一个 Parameters 节点，并且它应该紧跟在 Syntax 节点之后。

   <command:command>
     <command:details></command:details>
     <maml:description></maml:description>
     <command:syntax></command:syntax>
     <command:parameters>
     </command:parameters>
   </command:command>
   

3. 在“参数”节点中，为 cmdlet 的每个参数添加一个参数节点，如下所示。

   在此示例中，为三个参数添加了一个 Parameter 节点。

   <command:parameters>
     <command:parameter></command:parameter>
     <command:parameter></command:parameter>
     <command:parameter></command:parameter>
   </command:parameters>
   

   由于这些与 Syntax 节点中使用的 XML 标记相同，并且此处指定的参数必须与 Syntax 节点指定的参数匹配，因此您可以复制 参数节点，并将其粘贴到参数节点中。但是，请确保仅复制参数节点的一个实例，即使在语法中的多个参数集中指定了该参数。

4. 对于每个参数节点，设置定义每个参数特征的属性值。这些属性包括以下属性：必需、通配、管道输入和位置。

   <command:parameters>
     <command:parameter required="true" globbing="true"
              pipelineInput="false" position="named">
     </command:parameter>
     <command:parameter required="false" globbing="false"
              pipelineInput="false" position="named">
     </command:parameter>
     <command:parameter required="false" globbing="false"
              pipelineInput="false" position="named" ></command:parameter>
   </command:parameters>
   

5. 对于每个参数节点，添加参数的名称。以下是添加到 Parameter 节点的参数名称示例。

   <command:parameters>
     <command:parameter required="true" globbing="true"
              pipelineInput="false" position="named">
       <maml:name> Add parameter name...  </maml:name>
     </command:parameter>
   </command:parameters>
   

6. 对于每个参数节点，添加参数的描述。以下是添加到参数节点的参数描述的示例。

   <command:parameters>
     <command:parameter required="true" globbing="true"
              pipelineInput="false" position="named">
       <maml:name> Add parameter name...  </maml:name>
       <maml:description>
         <maml:para> Add parameter description... </maml:para>
       </maml:description>
     </command:parameter>
   </command:parameters>
   

7. 对于每个参数节点，添加参数的.NET 类型。参数类型与参数名称一起显示。

   以下是添加到 Parameter 节点的参数 .NET 类型的示例。

   <command:parameters>
     <command:parameter required="true" globbing="true"
              pipelineInput="false" position="named">
       <maml:name> Add parameter name...  </maml:name>
       <maml:description>
         <maml:para> Add parameter description... </maml:para>
       </maml:description>
       <dev:type> Add .NET Framework type... </dev:type>
     </command:parameter>
   </command:parameters>
   

8. 对于每个参数节点，添加参数的默认值。显示内容时参数说明中添加如下一句：DefaultValue为默认值。

   以下是将参数默认值添加到 Parameter 节点的示例。

   <command:parameters>
     <command:parameter required="true" globbing="true"
              pipelineInput="false" position="named">
       <maml:name> Add parameter name...  </maml:name>
       <maml:description>
         <maml:para> Add parameter description... </maml:para>
       </maml:description>
       <dev:type> Add .NET Framework type... </dev:type>
       <dev:defaultvalue> Add default value...</dev:defaultvalue>
     </command:parameter>
   </command:parameters>
   

9. 对于每个具有多个值的参数，添加一个 possibleValues 节点。

   以下是 possibleValues 节点的示例，它定义了参数的两个可能值

   <dev:possibleValues>
     <dev:possibleValue>
       <dev:value>Unknown</dev:value>
       <maml:description>
         <maml:para></maml:para>
       </maml:description>
     </dev:possibleValue>
     <dev:possibleValue>
       <dev:value>String</dev:value>
       <maml:description>
         <maml:para></maml:para>
       </maml:description>
     </dev:possibleValue>
   </dev:possibleValues>
   

添加参数时需要记住以下几点。

• 参数的属性不会显示在 cmdlet 帮助主题的所有视图中。但是，当用户请求 Full (Get-Help -Full) 或 Parameter 时，它们会显示在参数说明后面的表格中 (Get-Help -Parameter) 主题视图。

• 参数描述是 cmdlet 帮助主题中最重要的部分之一。描述既要简短又要详尽。另外，请记住，如果参数描述变得太长，例如当两个参数相互交互时，您可以在 cmdlet 帮助主题的 NOTES 部分中添加更多内容。

  参数描述提供两种类型的信息。

• 使用参数时 cmdlet 执行的操作。

• 参数的合法值是多少。

• 由于参数值表示为 .NET 对象，因此与传统命令行帮助相比，用户需要更多有关这些值的信息。告诉用户参数设计接受什么类型的数据，并包括示例。

参数的默认值是未在命令行上指定该参数时使用的值。请注意，默认值是可选的，某些参数不需要默认值，例如必需参数。但是，您应该为大多数可选参数指定默认值。

默认值有助于用户了解不使用该参数的效果。非常具体地描述默认值，例如可选路径的“当前目录”或“PowerShell 安装目录 ($PSHOME)”。您还可以编写一个描述默认值的句子，例如用于 PassThru 参数的以下句子：“如果未指定 PassThru，则 cmdlet 不会将对象传递到管道中。”此外，由于该值显示在字段名称默认值的对面，因此您无需在条目中包含术语“默认值”。

该参数的默认值不会显示在 cmdlet 帮助主题的所有视图中。但是，当用户请求 Full (Get-Help -Full) 或主题的参数 (Get-Help -Parameter) 视图。

以下 XML 显示了添加到 <command:parameter> 节点的一对 <dev:defaultValue> 标记。请注意，默认值紧跟在结束 </command:parameterValue> 标记（当指定参数值时）或结束 </maml:description> 标记之后。参数说明。姓名。

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
  </command:parameter>
</command:parameters>

为枚举类型添加值

如果参数有多个值或枚举类型的值，您可以使用可选的 <dev:possibleValues> 节点。该节点允许您指定多个值的名称和描述。

请注意，枚举值的说明不会出现在 Get-Help cmdlet 显示的任何默认帮助视图中，但其他帮助查看器可能会在其视图中显示此内容。

以下 XML 显示了指定了两个值的 <dev:possibleValues> 节点。

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
    <dev:possibleValues>
      <dev:possibleValue>
        <dev:value> Value 1 </dev:value>
        <maml:description>
          <maml:para> Description 1 </maml:para>
        </maml:description>
      <dev:possibleValue>
      <dev:possibleValue>
        <dev:value> Value 2 </dev:value>
        <maml:description>
          <maml:para> Description 2 </maml:para>
        </maml:description>
      <dev:possibleValue>
    </dev:possibleValues>
  </command:parameter>
</command:parameters>