Cómo agregar parámetros dinámicos a un tema de Ayuda de proveedorHow to Add Dynamic Parameters to a Provider Help Topic

En esta sección se explica cómo rellenar la sección de parámetros dinámicos de un tema de ayuda del proveedor.This section explains how to populate the DYNAMIC PARAMETERS section of a provider help topic.

Los parámetros dinámicos son parámetros de un cmdlet o una función que solo están disponibles en las condiciones especificadas.Dynamic parameters are parameters of a cmdlet or function that are available only under specified conditions.

Los parámetros dinámicos que se documentan en un tema de ayuda del proveedor son los parámetros dinámicos que el proveedor agrega al cmdlet o la función cuando el cmdlet o la función se usa en la unidad del proveedor.The dynamic parameters that are documented in a provider help topic are the dynamic parameters that the provider adds to the cmdlet or function when the cmdlet or function is used in the provider drive.

Los parámetros dinámicos también se pueden documentar en la ayuda de cmdlet personalizada para un proveedor.Dynamic parameters can also be documented in custom cmdlet help for a provider. Al escribir la ayuda de proveedor y la ayuda de cmdlet personalizada para un proveedor, incluya la documentación de parámetros dinámicos en ambos documentos.When writing both provider help and custom cmdlet help for a provider, include the dynamic parameter documentation in both documents.

Si un proveedor no implementa ningún parámetro dinámico, el tema de ayuda del proveedor contiene un DynamicParameters elemento vacío.If a provider does not implement any dynamic parameters, the provider help topic contains an empty DynamicParameters element.

Para agregar parámetros dinámicosTo Add Dynamic Parameters

  1. En el <AssemblyName>.dll-help.xml archivo, dentro del providerHelp elemento, agregue un DynamicParameters elemento.In the <AssemblyName>.dll-help.xml file, within the providerHelp element, add a DynamicParameters element. El DynamicParameters elemento debe aparecer después del Tasks elemento y antes del RelatedLinks elemento.The DynamicParameters element should appear after the Tasks element and before the RelatedLinks element.

    Por ejemplo:For example:

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

    Si el proveedor no implementa ningún parámetro dinámico, el DynamicParameters elemento puede estar vacío.If the provider does not implement any dynamic parameters, the DynamicParameters element can be empty.

  2. En el DynamicParameters elemento, agregue un elemento para cada parámetro dinámico DynamicParameter .Within the DynamicParameters element, for each dynamic parameter, add a DynamicParameter element.

    Por ejemplo:For example:

    <DynamicParameters/>
        <DynamicParameter>
        </DynamicParameter>
    </DynamicParameters>
    
  3. En cada DynamicParameter elemento, agregue un Name CmdletSupported elemento y.In each DynamicParameter element, add a Name and CmdletSupported element.

    • Nombre: especifica el nombre del parámetro.Name - Specifies the parameter name
    • CmdletSupported: especifica los cmdlets en los que el parámetro es válido.CmdletSupported - Specifies the cmdlets in which the parameter is valid. Escriba una lista separada por comas de nombres de cmdlet.Type a comma-separated list of cmdlet names.

    Por ejemplo, el siguiente XML documenta el Encoding parámetro dinámico que el proveedor filesystem de Windows PowerShell agrega a Add-Content los Get-Content Set-Content cmdlets,,.For example, the following XML documents the Encoding dynamic parameter that the Windows PowerShell FileSystem provider adds to the Add-Content, Get-Content, Set-Content cmdlets.

    <DynamicParameters/>
        <DynamicParameter>
            <Name> Encoding </Name>
            <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported>
    </DynamicParameters>
    
    
  4. En cada DynamicParameter elemento, agregue un Type elemento.In each DynamicParameter element, add a Type element. El Type elemento es un contenedor para el Name elemento que contiene el tipo .net del valor del parámetro dinámico.The Type element is a container for the Name element which contains the .NET type of the value of the dynamic parameter.

    Por ejemplo, el siguiente XML muestra que el tipo .NET del Encoding parámetro dinámico es la enumeración FileSystemCmdletProviderEncoding .For example, the following XML shows that the .NET type of the Encoding dynamic parameter is the FileSystemCmdletProviderEncoding enumeration.

    <DynamicParameters/>
        <DynamicParameter>
            <Name> Encoding </Name>
            <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported>
            <Type>
                <Name> Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding </Name>
            <Type>
    ...
    </DynamicParameters>
    
  5. Agregue el Description elemento, que contiene una breve descripción del parámetro dinámico.Add the Description element, which contains a brief description of the dynamic parameter. Al redactar la descripción, siga las directrices prescritas para todos los parámetros de cmdlet en Cómo agregar información de parámetros.When composing the description, use the guidelines prescribed for all cmdlet parameters in How to Add Parameter Information.

    Por ejemplo, el código XML siguiente incluye la descripción del Encoding parámetro dinámico.For example, the following XML includes the description of the Encoding dynamic parameter.

    <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>
    
  6. Agregue el PossibleValues elemento y sus elementos secundarios.Add the PossibleValues element and its child elements. Juntos, estos elementos describen los valores del parámetro dinámico.Together, these elements describe the values of the dynamic parameter. Este elemento está diseñado para los valores enumerados.This element is designed for enumerated values. Si el parámetro dinámico no toma un valor, como es el caso de un parámetro de modificador o los valores no se pueden enumerar, agregue un PossibleValues elemento vacío.If the dynamic parameter does not take a value, such as is the case with a switch parameter, or the values cannot be enumerated, add an empty PossibleValues element.

    En la tabla siguiente se enumeran y describen el PossibleValues elemento y sus elementos secundarios.The following table lists and describes the PossibleValues element and its child elements.

    • PossibleValues: este elemento es un contenedor.PossibleValues - This element is a container. A continuación se describen sus elementos secundarios.Its child elements are described below. Agregue un PossibleValues elemento a cada tema de ayuda del proveedor.Add one PossibleValues element to each provider help topic. El elemento puede estar vacío.The element can be empty.
    • PossibleValue: este elemento es un contenedor.PossibleValue - This element is a container. A continuación se describen sus elementos secundarios.Its child elements are described below. Agregue un PossibleValue elemento para cada valor del parámetro dinámico.Add one PossibleValue element for each value of the dynamic parameter.
    • Valor: especifica el nombre del valor.Value - Specifies the value name.
    • Descripción: este elemento contiene un Para elemento.Description - This element contains a Para element. El texto del Para elemento describe el valor que se denomina en el Value elemento.The text in the Para element describes the value that is named in the Value element.

    Por ejemplo, el siguiente código XML muestra un PossibleValue elemento del Encoding parámetro dinámico.For example, the following XML shows one PossibleValue element of the Encoding dynamic parameter.

    <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>
    

EjemploExample

En el ejemplo siguiente se muestra el DynamicParameters elemento del Encoding parámetro dinámico.The following example shows the DynamicParameters element of the Encoding dynamic parameter.

<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>