Jak přidat informace o parametrech

Článek
12/09/2021

Tato část popisuje, jak přidat obsah, který se zobrazí v části Parameters tématu nápovědy k rutině. Oddíl Parameters v tématu nápovědy obsahuje seznam všech parametrů rutiny a poskytuje podrobný popis jednotlivých parametrů.

Obsah oddílu Parameters by měl být v souladu s obsahem oddílu syntax v tématu nápovědy. Je zodpovědný za to, že má autor s potřebami, aby uzel syntaxe i parametry obsahoval podobné prvky XML.

Poznámka

Úplný přehled souboru s nápovědu otevřete otevřením jednoho ze dll-Help.xml souborů umístěných v instalačním adresáři prostředí PowerShell. Microsoft.PowerShell.Commands.Management.dll-Help.xmlSoubor například obsahuje obsah pro několik rutin PowerShellu.

Přidání parametrů

Otevřete soubor s nápovědu k rutině a vyhledejte uzel příkazu pro rutinu, kterou chcete zdokumentovat. Pokud přidáváte novou rutinu, budete muset vytvořit nový uzel příkazů . Váš soubor s přehledem bude obsahovat uzel příkazů pro každou rutinu, pro kterou poskytujete obsah pro nápovědu. Tady je příklad prázdného uzlu příkazu .
```
<command:command>
</command:command>
```

V uzlu příkazu vyhledejte uzel Popis a přidejte uzel parametry , jak je znázorněno níže. Je povolen pouze jeden uzel parametrů a měl by následovat po uzlu syntaxe .

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

V uzlu Parameters přidejte uzel parametru pro každý parametr rutiny, jak je znázorněno níže.

V tomto příkladu je přidán uzel parametru pro tři parametry.
```
<command:parameters>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
</command:parameters>
```
Vzhledem k tomu, že se jedná o stejné značky XML, které se používají v uzlu syntaxe a protože zadané parametry se musí shodovat s parametry určenými uzlem syntaxe , můžete zkopírovat uzly parametrů z uzlu syntaxe a vložit je do uzlu Parameters . Nezapomeňte však zkopírovat pouze jednu instanci uzlu parametru , i když je parametr zadán v několika sadách parametrů v syntaxi.

Pro každý uzel parametru nastavte hodnoty atributu definující charakteristiky každého parametru. Mezi tyto atributy patří následující: požadováno, expanze, pipelineinput a pozice.

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

Pro každý uzel parametru přidejte název parametru. Tady je příklad názvu parametru přidaného do uzlu parametru .

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

Pro každý uzel parametru přidejte popis parametru. Zde je příklad popisu parametru přidaného do uzlu parametru .

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

Pro každý uzel parametru přidejte typ .NET parametru. Typ parametru se zobrazí spolu s názvem parametru.

Zde je příklad typu .NET, který je přidán do uzlu Parameter .

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

Pro každý uzel parametru přidejte výchozí hodnotu parametru. Po zobrazení obsahu je do popisu parametru přidána následující věta: výchozí hodnota je VýchozíHodnota .

Tady je příklad výchozí hodnoty parametru, který je přidán do uzlu Parameter .

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

Pro každý parametr, který má více hodnot, přidejte uzel possibleValues .

Tady je příklad uzlu possibleValues , který definuje dvě možné hodnoty 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>

Tady jsou některé věci, které byste si měli pamatovat při přidávání parametrů.

Atributy parametru nejsou zobrazeny ve všech zobrazeních tématu nápovědy k rutině. Jsou však zobrazeny v tabulce následující po popisu parametru, když uživatel požaduje úplný ( Get-Help <cmdletname> -Full ) nebo parametr ( Get-Help <cmdletname> -Parameter ) zobrazení tématu.
Popis parametru je jednou z nejdůležitějších částí tématu nápovědy k rutině. Popis by měl být krátký a také vyčerpávající. Nezapomeňte také, že pokud je popis parametru příliš dlouhý, například když dva parametry vzájemně komunikují, můžete přidat další obsah do oddílu poznámky tématu nápovědy k rutině.

Popis parametru poskytuje dva typy informací.
Co rutina provede při použití parametru.
Jaká je platná hodnota pro parametr.
Vzhledem k tomu, že hodnoty parametrů jsou vyjádřené jako objekty .NET, uživatelé potřebují další informace o těchto hodnotách, než by museli v tradiční nápovědě k příkazovému řádku. Sdělte uživateli, jaký typ dat má parametr přijmout, a uveďte příklady.

Výchozí hodnota parametru je hodnota, která se používá, pokud parametr není zadán v příkazovém řádku. Všimněte si, že výchozí hodnota je volitelná a není nutná pro některé parametry, například požadované parametry. Je však třeba zadat výchozí hodnotu pro většinu volitelných parametrů.

Výchozí hodnota pomáhá uživateli pochopit účinek nepoužití parametru. Pro volitelnou cestu popište specifickou výchozí hodnotu, například "aktuální adresář" nebo "instalační adresář prostředí PowerShell ( $PSHOME )". Můžete také napsat větu, která popisuje výchozí hodnotu, například následující větu, která se používá pro parametr passthru : "Pokud passthru není zadán, rutina neprojde objekty v kanálu." Vzhledem k tomu, že se hodnota zobrazuje u výchozí hodnoty názvu pole, nemusíte do položky zahrnout výraz "výchozí hodnota".

Výchozí hodnota parametru není zobrazená ve všech zobrazeních tématu nápovědy k rutině. Je však zobrazen v tabulce (spolu s atributy parametru) podle popisu parametru, když uživatel požádá o úplné ( Get-Help <cmdletname> -Full ) nebo parametr ( Get-Help <cmdletname> -Parameter ) zobrazení tématu.

Následující kód XML ukazuje dvojici <dev:defaultValue> značek přidaných do <command:parameter> uzlu. Všimněte si, že výchozí hodnota následuje hned za uzavírací </command:parameterValue> značkou (když je zadána hodnota parametru) nebo uzavírací </maml:description> značka popisu parametru. Jméno.

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

Přidat hodnoty pro výčtové typy

Pokud má parametr více hodnot nebo hodnot výčtového typu, můžete použít volitelný <dev:possibleValues> uzel. Tento uzel umožňuje zadat název a popis pro více hodnot.

Počítejte s tím, že popisy hodnot výčtu se nezobrazují v žádném z výchozích zobrazení Get-Help , která rutina zobrazuje, ale ostatní čtenáři pomocníka mohou tento obsah zobrazit v zobrazeních.

Následující kód XML znázorňuje <dev:possibleValues> uzel se dvěma zadanými hodnotami.

<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 přidat informace o parametrech

Přidání parametrů

Váš názor

Další materiály