Jak dodać informacje o parametrach

Artykuł
12/09/2021

W tej sekcji opisano sposób dodawania zawartości wyświetlanej w sekcji PARAMETRY w temacie Pomocy dotyczącej polecenia cmdlet. Sekcja PARAMETERS w temacie Pomocy zawiera listę wszystkich parametrów polecenia cmdlet oraz szczegółowy opis każdego parametru.

Zawartość sekcji PARAMETRY powinna być zgodna z zawartością sekcji SKŁADNIA w temacie Pomocy. Autor pomocy jest odpowiedzialny za zapewnienie, że zarówno w węźle Składnia, jak i Parametry znajdują się podobne elementy XML.

Uwaga

Aby uzyskać pełny widok pliku Pomocy, otwórz jeden z plików znajdujących dll-Help.xml się w katalogu instalacyjnym programu PowerShell. Na przykład plik Microsoft.PowerShell.Commands.Management.dll-Help.xml zawiera zawartość kilku poleceń cmdlet programu PowerShell.

Aby dodać parametry

Otwórz plik pomocy polecenia cmdlet i znajdź węzeł Polecenie dla udokumentowanego polecenia cmdlet. Jeśli dodajesz nowe polecenie cmdlet, musisz utworzyć nowy węzeł Polecenia. Plik Pomocy będzie zawierać węzeł Polecenia dla każdego polecenia cmdlet, dla których udostępniasz zawartość Pomocy. Oto przykład pustego węzła polecenia.
```
<command:command>
</command:command>
```

W węźle Polecenie znajdź węzeł Opis i dodaj węzeł Parametry, jak pokazano poniżej. Dozwolony jest tylko jeden węzeł Parametry, który powinien być natychmiast przestrzegany przez węzeł Składnia.

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

W węźle Parametry dodaj węzeł Parametr dla każdego parametru polecenia cmdlet, jak pokazano poniżej.

W tym przykładzie dodano węzeł Parametr dla trzech parametrów.
```
<command:parameters>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
</command:parameters>
```
Ponieważ są to te same tagi XML, które są używane w węźle Składnia, a parametry określone w tym miejscu muszą być zgodne z parametrami określonymi w węźle Składnia, można skopiować węzły parametrów z węzła Składnia i wkleić je do węzła Parametry. Pamiętaj jednak, aby skopiować tylko jedno wystąpienie węzła Parametr, nawet jeśli parametr jest określony w wielu zestawach parametrów w składni.

Dla każdego węzła parametru ustaw wartości atrybutów definiujące charakterystykę każdego parametru. Te atrybuty obejmują następujące elementy: required, globbing, pipelineinput i position.

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

Dla każdego węzła Parametr dodaj nazwę parametru. Oto przykład nazwy parametru dodanej do węzła Parametr.

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

Dla każdego węzła Parametr dodaj opis parametru. Oto przykład opisu parametru dodanego do węzła Parametr.

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

Dla każdego węzła parametru dodaj typ .NET parametru. Zostanie wyświetlony typ parametru wraz z nazwą parametru.

Oto przykład typu parametru .NET dodanego do węzła Parametr.

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

Dla każdego węzła parametru dodaj wartość domyślną parametru . Następujące zdanie jest dodawane do opisu parametru podczas wyświetlania zawartości: DefaultValue jest wartością domyślną.

Oto przykład dodania wartości domyślnej parametru do węzła Parametr.

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

Dla każdego parametru, który ma wiele wartości, dodaj węzeł possibleValues.

Oto przykład węzła possibleValues, który definiuje dwie możliwe wartości dla parametru

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

Oto kilka rzeczy, o których należy pamiętać podczas dodawania parametrów.

Atrybuty parametru nie są wyświetlane we wszystkich widokach tematu pomocy polecenia cmdlet. Są one jednak wyświetlane w tabeli po opisie parametru, gdy użytkownik pyta o widok Pełny ( ) lub Get-Help <cmdletname> -Full Parametr Get-Help <cmdletname> -Parameter () tematu.
Opis parametru jest jedną z najważniejszych części tematu pomocy polecenia cmdlet. Opis powinien być krótki, a także dokładny. Należy również pamiętać, że jeśli opis parametru staje się zbyt długi, na przykład gdy dwa parametry współdziałają ze sobą, możesz dodać więcej zawartości w sekcji UWAGI w temacie Pomocy polecenia cmdlet.

Opis parametru zawiera dwa typy informacji.
Co polecenie cmdlet robi, gdy parametr jest używany.
Jaka jest wartość prawna dla parametru .
Ponieważ wartości parametrów są wyrażane jako obiekty .NET, użytkownicy potrzebują więcej informacji o tych wartościach niż w tradycyjnej pomocy wiersza polecenia. Poinformuj użytkownika, jakiego typu dane parametr ma akceptować, i dołącz przykłady.

Wartość domyślna parametru jest wartość, która jest używana, jeśli parametr nie jest określony w wierszu polecenia. Należy pamiętać, że wartość domyślna jest opcjonalna i nie jest wymagana w przypadku niektórych parametrów, takich jak wymagane parametry. Należy jednak określić wartość domyślną dla większości parametrów opcjonalnych.

Wartość domyślna pomaga użytkownikowi zrozumieć efekt nie używania parametru . Opisz wartość domyślną, na przykład "Bieżący katalog" lub "Katalog instalacyjny programu PowerShell ( $PSHOME )" dla ścieżki opcjonalnej. Można również napisać zdanie opisujące wartość domyślną, na przykład następujące zdanie używane dla parametru PassThru: "Jeśli passThru nie zostanie określony, polecenie cmdlet nie przekaże obiektów do potoku". Ponadto ponieważ wartość jest wyświetlana na przeciwieństwo nazwy pola Wartość domyślna, nie trzeba uwzględniać w wpisie terminu "wartość domyślna".

Wartość domyślna parametru nie jest wyświetlana we wszystkich widokach tematu pomocy polecenia cmdlet. Jest on jednak wyświetlany w tabeli (wraz z atrybutami parametrów) po opisie parametru, gdy użytkownik zapyta o widok Pełny ( ) lub Get-Help <cmdletname> -Full Parametr Get-Help <cmdletname> -Parameter () tematu.

Poniższy kod XML przedstawia parę <dev:defaultValue> tagów dodanych do <command:parameter> węzła. Zwróć uwagę, że wartość domyślna następuje bezpośrednio po tagu zamykającym (po podano wartość parametru) lub tagu zamykającym </command:parameterValue> </maml:description> opisu parametru. Nazwa.

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

Dodawanie wartości dla typów wyliczeniowych

Jeśli parametr ma wiele wartości lub wartości typu wyliczanego, można użyć opcjonalnego <dev:possibleValues> węzła. Ten węzeł umożliwia określenie nazwy i opisu wielu wartości.

Należy pamiętać, że opisy wyliczanych wartości nie są wyświetlane w żadnym z domyślnych widoków Pomocy wyświetlanych przez polecenie cmdlet, ale inne przeglądarki Pomocy mogą wyświetlać tę zawartość w Get-Help widokach.

Poniższy kod XML przedstawia <dev:possibleValues> węzeł z dwiema określonymi wartościami.

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

Jak dodać informacje o parametrach

Aby dodać parametry

Opinia

Dodatkowe zasoby