Jak dodać parametry dynamiczne do tematu pomocy dotyczącego dostawcy

  • Artykuł

W tej sekcji wyjaśniono, jak wypełnić sekcję PARAMETRY DYNAMICZNE tematu pomocy dostawcy.

Parametry dynamiczne to parametry polecenia cmdlet lub funkcji, które są dostępne tylko w określonych warunkach.

Parametry dynamiczne udokumentowane w temacie pomocy dostawcy to parametry dynamiczne, które dostawca dodaje do polecenia cmdlet lub funkcji, gdy polecenie cmdlet lub funkcja jest używana na dysku dostawcy.

Parametry dynamiczne można również udokumentować w pomocy niestandardowego polecenia cmdlet dla dostawcy. Podczas pisania zarówno pomocy dostawcy, jak i pomocy dotyczącej polecenia cmdlet niestandardowego dla dostawcy należy uwzględnić dokumentację parametrów dynamicznych w obu dokumentach.

Jeśli dostawca nie implementuje żadnych parametrów dynamicznych, temat pomocy dostawcy zawiera pusty DynamicParameters element.

Aby dodać parametry dynamiczne

  1. W <AssemblyName>.dll-help.xml pliku w providerHelp elemencie dodaj DynamicParameters element . Element DynamicParameters powinien pojawić się po Tasks elemencie i przed RelatedLinks elementem .

    Na przykład:

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

    Jeśli dostawca nie implementuje żadnych parametrów dynamicznych, DynamicParameters element może być pusty.

  2. W DynamicParameters elemencie dla każdego parametru dynamicznego dodaj DynamicParameter element .

    Na przykład:

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

  3. W każdym DynamicParameter elemencie dodaj Name element i CmdletSupported .

    • Nazwa — określa nazwę parametru
    • CmdletSupported — określa polecenia cmdlet, w których parametr jest prawidłowy. Wpisz rozdzielaną przecinkami listę nazw polecenia cmdlet.

    Na przykład poniższy kod XML dokumentuje parametr dynamiczny, który dostawca Windows PowerShell FileSystem dodaje do Encoding Add-Content polecenia Get-Content cmdlet , , Set-Content .

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

  4. W każdym DynamicParameter elemencie dodaj Type element . Element Type jest kontenerem dla Name elementu , który zawiera typ .NET wartości parametru dynamicznego.

    Na przykład poniższy kod XML pokazuje, że typem .NET parametru dynamicznego jest Encoding wyliczenie FileSystemCmdletProviderEncoding.

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

  5. Dodaj Description element , który zawiera krótki opis parametru dynamicznego. Podczas composing opis, należy użyć wytycznych określonych dla wszystkich parametrów polecenia cmdlet w Jak dodać informacje o parametrach.

    Na przykład poniższy kod XML zawiera opis Encoding parametru dynamicznego.

    <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. Dodaj PossibleValues element i jego elementy podrzędne. Razem te elementy opisują wartości parametru dynamicznego. Ten element jest przeznaczony dla wartości wyliczeniowych. Jeśli parametr dynamiczny nie ma wartości, takiej jak w przypadku parametru switch lub nie można wyliczyć wartości, dodaj pusty PossibleValues element.

    W poniższej tabeli wymieniono i opisano PossibleValues element i jego elementy podrzędne.

    • PossibleValues — ten element jest kontenerem. Jej elementy podrzędne zostały opisane poniżej. Dodaj jeden PossibleValues element do każdego tematu pomocy dostawcy. Element może być pusty.
    • PossibleValue — ten element jest kontenerem. Jej elementy podrzędne zostały opisane poniżej. Dodaj jeden PossibleValue element dla każdej wartości parametru dynamicznego.
    • Wartość — określa nazwę wartości.
    • Opis — ten element zawiera Para element . Tekst w Para elemencie opisuje wartość, która jest nazwana w Value elemencie .

    Na przykład poniższy kod XML pokazuje PossibleValue jeden element Encoding parametru dynamicznego.

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

Przykład

W poniższym przykładzie DynamicParameters pokazano element Encoding parametru dynamicznego.

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