如何将动态参数添加到提供程序帮助主题

笔记

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

本部分介绍如何填充提供程序帮助主题的动态参数部分。

动态参数是仅在指定条件下可用的 cmdlet 或函数的参数。

提供程序帮助主题中记录的动态参数是当在提供程序驱动器中使用 cmdlet 或函数时提供程序添加到 cmdlet 或函数的动态参数。

动态参数也可以记录在提供商的自定义 cmdlet 帮助中。在为提供程序编写提供程序帮助和自定义 cmdlet 帮助时，请在两个文档中都包含动态参数文档。

如果提供程序未实现任何动态参数，则提供程序帮助主题将包含一个空的 DynamicParameters 元素。

添加动态参数

1. 在 <AssemblyName>.dll-help.xml 文件的 providerHelp 元素中，添加 DynamicParameters 元素。 DynamicParameters 元素应出现在 Tasks 元素之后、RelatedLinks 元素之前。

   例如：

   <providerHelp>
       <Tasks>
       </Tasks>
       <DynamicParameters>
       </DynamicParameters>
       <RelatedLinks>
       </RelatedLinks>
   </providerHelp>
   

   如果提供程序未实现任何动态参数，则 DynamicParameters 元素可以为空。

2. 在 DynamicParameters 元素中，为每个动态参数添加一个 DynamicParameter 元素。

   例如：

   <DynamicParameters/>
       <DynamicParameter>
       </DynamicParameter>
   </DynamicParameters>
   

3. 在每个 DynamicParameter 元素中，添加 Name 和 CmdletSupported 元素。

   • 名称 - 指定参数名称
4. CmdletSupported - 指定参数在其中有效的 cmdlet。键入以逗号分隔的 cmdlet 名称列表。

例如，以下 XML 记录了 Windows PowerShell 文件系统提供程序添加到 Add-Content、Get-Content、Set-Content cmdlet。

<DynamicParameters/>
    <DynamicParameter>
        <Name> Encoding </Name>
        <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported>
</DynamicParameters>

5. 在每个 DynamicParameter 元素中，添加一个 Type 元素。 Type 元素是 Name 元素的容器，其中包含动态参数值的 .NET 类型。

   例如，以下 XML 显示 Encoding 动态参数的 .NET 类型是 FileSystemCmdletProviderEncoding 枚举。

   <DynamicParameters/>
       <DynamicParameter>
           <Name> Encoding </Name>
           <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported>
           <Type>
               <Name> Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding </Name>
           <Type>
   ...
   </DynamicParameters>
   

6. 添加 Description 元素，其中包含动态参数的简短描述。编写描述时，请使用如何添加参数信息中为所有 cmdlet 参数规定的准则。

   例如，以下 XML 包含 Encoding 动态参数的描述。

   <DynamicParameters/>
       <DynamicParameter>
           <Name> Encoding </Name>
           <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported>
           <Type>
               <Name> Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding </Name>
           <Type>
           <Description> Specifies the encoding of the output file that contains the content. </Description>
   ...
   </DynamicParameters>
   

7. 添加 PossibleValues 元素及其子元素。这些元素一起描述动态参数的值。该元素是为枚举值而设计的。如果动态参数不带值（例如 switch 参数的情况），或者无法枚举值，请添加一个空的 PossibleValues 元素。

   下表列出并描述了 PossibleValues 元素及其子元素。

   • possibleValues - 该元素是一个容器。其子元素如下所述。向每个提供程序帮助主题添加一个 PossibleValues 元素。该元素可以为空。
8. possibleValue - 该元素是一个容器。其子元素如下所述。为动态参数的每个值添加一个 PossibleValue 元素。
9. 值 - 指定值名称。
10. 描述 - 该元素包含一个 Para 元素。 Para 元素中的文本描述 Value 元素中命名的值。

例如，以下 XML 显示 Encoding 动态参数的一个 PossibleValue 元素。

<DynamicParameters/>
    <DynamicParameter>
...
        <Description> Specifies the encoding of the output file that contains the content. </Description>
        <PossibleValues>
            <PossibleValue>
                <Value> ASCII </Value>
                <Description>
                    <para> Uses the encoding for the ASCII (7-bit) character set. </para>
                </Description>
            </PossibleValue>
...
        </PossibleValues>
</DynamicParameters>

例子

以下示例显示 Encoding 动态参数的 DynamicParameters 元素。

<DynamicParameters/>
    <DynamicParameter>
        <Name> Encoding </Name>
        <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported>
        <Type>
            <Name> Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding </Name>
        <Type>
        <Description> Specifies the encoding of the output file that contains the content. </Description>
        <PossibleValues>
            <PossibleValue>
                <Value> ASCII </Value>
                <Description>
                    <para> Uses the encoding for the ASCII (7-bit) character set. </para>
                </Description>
            </PossibleValue>
            <PossibleValue>
                <Value> Unicode </Value>
                <Description>
                    <para> Encodes in UTF-16 format using the little-endian byte order. </para>
                </Description>
            </PossibleValue>
        </PossibleValues>
</DynamicParameters>