Come aggiungere parametri dinamici a un argomento della Guida dei providerHow to Add Dynamic Parameters to a Provider Help Topic

In questa sezione viene illustrato come popolare la sezione parametri dinamici di un argomento della guida del provider.This section explains how to populate the DYNAMIC PARAMETERS section of a provider help topic.

I parametri dinamici sono parametri di un cmdlet o di una funzione disponibili solo in condizioni specificate.Dynamic parameters are parameters of a cmdlet or function that are available only under specified conditions.

I parametri dinamici documentati in un argomento della guida del provider sono i parametri dinamici aggiunti dal provider al cmdlet o alla funzione quando si utilizza il cmdlet o la funzione nell'unità del provider.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.

I parametri dinamici possono anche essere documentati nella Guida personalizzata dei cmdlet per un provider.Dynamic parameters can also be documented in custom cmdlet help for a provider. Quando si scrivono sia la guida del provider che la guida personalizzata sui cmdlet per un provider, includere la documentazione relativa ai parametri dinamici in entrambi i documenti.When writing both provider help and custom cmdlet help for a provider, include the dynamic parameter documentation in both documents.

Se un provider non implementa parametri dinamici, l'argomento della guida del provider contiene un DynamicParameters elemento vuoto.If a provider does not implement any dynamic parameters, the provider help topic contains an empty DynamicParameters element.

Per aggiungere parametri dinamiciTo Add Dynamic Parameters

  1. Nel <AssemblyName>.dll-help.xml file, all'interno dell' providerHelp elemento, aggiungere un DynamicParameters elemento.In the <AssemblyName>.dll-help.xml file, within the providerHelp element, add a DynamicParameters element. L' DynamicParameters elemento deve essere visualizzato dopo l' Tasks elemento e prima dell' RelatedLinks elemento.The DynamicParameters element should appear after the Tasks element and before the RelatedLinks element.

    Ad esempio:For example:

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

    Se il provider non implementa parametri dinamici, l' DynamicParameters elemento può essere vuoto.If the provider does not implement any dynamic parameters, the DynamicParameters element can be empty.

  2. All'interno dell' DynamicParameters elemento, per ogni parametro dinamico, aggiungere un DynamicParameter elemento.Within the DynamicParameters element, for each dynamic parameter, add a DynamicParameter element.

    Ad esempio:For example:

    <DynamicParameters/>
        <DynamicParameter>
        </DynamicParameter>
    </DynamicParameters>
    
  3. In ogni DynamicParameter elemento aggiungere un Name elemento e CmdletSupported .In each DynamicParameter element, add a Name and CmdletSupported element.

    • Nome: specifica il nome del parametroName - Specifies the parameter name
    • CmdletSupported: specifica i cmdlet in cui il parametro è valido.CmdletSupported - Specifies the cmdlets in which the parameter is valid. Digitare un elenco delimitato da virgole di nomi di cmdlet.Type a comma-separated list of cmdlet names.

    Il codice XML seguente, ad esempio, documenta il Encoding parametro dinamico aggiunto dal provider FileSystem di Windows PowerShell Add-Content ai Get-Content cmdlet,, Set-Content .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. In ogni DynamicParameter elemento aggiungere un Type elemento.In each DynamicParameter element, add a Type element. L' Type elemento è un contenitore per l' Name elemento che contiene il tipo .NET del valore del parametro dinamico.The Type element is a container for the Name element which contains the .NET type of the value of the dynamic parameter.

    Il codice XML seguente, ad esempio, indica che il tipo .NET del Encoding parametro dinamico è l'enumerazione 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. Aggiungere l' Description elemento, che contiene una breve descrizione del parametro dinamico.Add the Description element, which contains a brief description of the dynamic parameter. Quando si compone la descrizione, utilizzare le linee guida previste per tutti i parametri del cmdlet in come aggiungere informazioni sui parametri.When composing the description, use the guidelines prescribed for all cmdlet parameters in How to Add Parameter Information.

    Il codice XML seguente, ad esempio, include la descrizione del Encoding parametro dinamico.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. Aggiungere l' PossibleValues elemento e i relativi elementi figlio.Add the PossibleValues element and its child elements. Insieme, questi elementi descrivono i valori del parametro dinamico.Together, these elements describe the values of the dynamic parameter. Questo elemento è progettato per i valori enumerati.This element is designed for enumerated values. Se il parametro dinamico non accetta un valore, come nel caso di un parametro switch, oppure non è possibile enumerare i valori, aggiungere un PossibleValues elemento vuoto.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.

    La tabella seguente elenca e descrive l' PossibleValues elemento e i relativi elementi figlio.The following table lists and describes the PossibleValues element and its child elements.

    • PossibleValues-questo elemento è un contenitore.PossibleValues - This element is a container. I relativi elementi figlio sono descritti di seguito.Its child elements are described below. Aggiungere un PossibleValues elemento a ogni argomento della guida del provider.Add one PossibleValues element to each provider help topic. L'elemento può essere vuoto.The element can be empty.
    • PossibleValue-questo elemento è un contenitore.PossibleValue - This element is a container. I relativi elementi figlio sono descritti di seguito.Its child elements are described below. Aggiungere un PossibleValue elemento per ogni valore del parametro dinamico.Add one PossibleValue element for each value of the dynamic parameter.
    • Valore: specifica il nome del valore.Value - Specifies the value name.
    • Description: questo elemento contiene un Para elemento.Description - This element contains a Para element. Il testo nell' Para elemento descrive il valore denominato nell' Value elemento.The text in the Para element describes the value that is named in the Value element.

    Il codice XML seguente, ad esempio, Mostra un PossibleValue elemento del Encoding parametro dinamico.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>
    

EsempioExample

Nell'esempio seguente viene illustrato l' DynamicParameters elemento del Encoding parametro dinamico.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>