Přidání syntaxe do tématu nápovědy k rutině

Článek
03/25/2025

Poznámka:

Ruční vytváření nápovědy založené na JAZYCE XML je velmi obtížné. Modul PlatyPS umožňuje psát nápovědu v Markdownu a pak ji převést na nápovědu založenou na jazyce XML. To usnadňuje psaní a údržbu nápovědy. PlatyPS vám také můžou vytvořit balíčky aktualizovatelné nápovědy. Další informace naleznete v tématu Vytvoření nápovědy založené na jazyce XML pomocí platyPS.

Než začnete kódovat KÓD XML pro syntaxi diagramu v souboru nápovědy rutiny, přečtěte si tuto část, abyste získali jasný obrázek o druhu dat, která potřebujete zadat, například atributy parametrů a způsob zobrazení těchto dat v diagramu syntaxe.

Atributy parametru

Povinný
- Pokud je hodnota true, musí se parametr objevit ve všech příkazech, které používají sadu parametrů.
- Pokud je hodnota false, parametr je volitelný ve všech příkazech, které používají sadu parametrů.
Postavení
- Pokud je parametr pojmenovaný, je požadován název parametru.
- Pokud je pozice, název parametru je volitelný. Pokud je vynechána, hodnota parametru musí být v zadané pozici v příkazu. Pokud je například hodnota position="1", hodnota parametru musí být první nebo pouze nepojmenovaná hodnota parametru v příkazu.
Vstup kanálu
- Pokud je true (ByValue), můžete vstup do parametru řadit. Vstup je přidružen k parametru ("vázáno") i v případě, že název vlastnosti a typ objektu neodpovídají očekávanému typu. Komponenty vazby parametrů PowerShellu se pokusí převést vstup na správný typ a příkaz selžou pouze v případech, kdy typ nelze převést. Hodnotu může přidružit pouze jeden parametr v sadě parametrů.
- Pokud má hodnotu true (ByPropertyName), můžete vstup do parametru převést. Vstup je však přidružen k parametru pouze v případě, že název parametru odpovídá názvu vlastnosti vstupního objektu. Pokud je například název parametru Path, objekty předané rutině jsou přidruženy k ho parametru pouze v případě, že objekt má vlastnost pojmenovanou cestu.
- Pokud true (ByValue, ByPropertyName), můžete vstup do parametru buď podle názvu vlastnosti, nebo podle hodnoty. Hodnotu může přidružit pouze jeden parametr v sadě parametrů.
- Pokud je nepravda, nemůžete do tohoto parametru zadávat kanály.
Globbing
- Pokud je hodnota true, může text, který uživatel zadá pro hodnotu parametru, obsahovat zástupné znaky.
- Pokud je hodnota false, text, který uživatel zadá pro hodnotu parametru, nemůže obsahovat zástupné znaky.

Atributy hodnot parametrů

Povinný
- Pokud je hodnota true, musí být zadaná hodnota použita při každém použití parametru v příkazu.
- Pokud je hodnota false, hodnota parametru je nepovinná. Hodnota je obvykle nepovinná jenom v případě, že se jedná o jednu z několika platných hodnot parametru, například v výčtovém typu.

Atribut Povinný hodnoty parametru se liší od atributu Povinné parametru.

Požadovaný atribut parametru označuje, jestli se má parametr (a jeho hodnota) zahrnout při vyvolání rutiny. Naproti tomu povinný atribut hodnoty parametru se používá pouze v případě, že je parametr součástí příkazu. Určuje, zda musí být s parametrem použita konkrétní hodnota.

Hodnoty parametrů, které jsou zástupnými symboly, jsou obvykle povinné a hodnoty parametrů, které jsou literálové, nejsou povinné, protože se jedná o jednu z několika hodnot, které se můžou s parametrem použít.

Shromažďování informací o syntaxi

Začněte názvem rutiny.
```
SYNTAX
    Get-Tech
```
Zobrazí seznam všech parametrů rutiny. Před název každého parametru zadejte spojovník (-). Parametry oddělte do sad parametrů (některé rutiny můžou mít jenom jednu sadu parametrů). V tomto příkladu má rutina Get-Tech dvě sady parametrů.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Spusťte každou sadu parametrů s názvem rutiny.

Nejprve vypíše výchozí sadu parametrů. Výchozí parametr je určen třídou rutiny.

Pro každou sadu parametrů nejprve vypíšete jeho jedinečný parametr, pokud nejsou k dispozici poziční parametry, které se musí zobrazit jako první. V předchozím příkladu jsou parametry Name a ID jedinečné pro tyto dvě sady parametrů (každá sada parametrů musí mít jeden parametr, který je pro danou sadu parametrů jedinečný). To uživatelům usnadňuje identifikaci parametru, který potřebují zadat pro sadu parametrů.

Vypište parametry v pořadí, v jakém by se měly zobrazit v příkazu. Pokud pořadí nezáleží, uveďte související parametry dohromady nebo uveďte seznam nejčastěji používaných parametrů jako první.

Pokud rutina podporuje Parametr ShouldProcess, nezapomeňte uvést parametry WhatIf a Confirm.

V diagramu syntaxe nevypisujte běžné parametry (například Podrobné, Ladění a ErrorAction). Rutina Get-Help tyto informace přidá za vás, když zobrazí téma nápovědy.
Přidejte hodnoty parametrů. V PowerShellu jsou hodnoty parametrů reprezentovány jejich typem .NET. Název typu však může být zkrácen, například "string" pro System.String.
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
Abbreviate typy tak dlouho, dokud jejich význam je jasný, například řetězec pro System.String a int pro System.Int32.

Uveďte všechny hodnoty výčtů, například parametr -Type v předchozím příkladu, který lze nastavit na základní nebo pokročilé.

Parametry přepínače, například -List v předchozím příkladu, nemají hodnoty.
K hodnotám parametrů, které jsou zástupné symboly, přidejte úhlové závorky ve srovnání s hodnotami parametrů, které jsou literály.
```
SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced
```

Uzavřete volitelné parametry a jejich vale do hranatých závorek.

SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

Uzavřete volitelné názvy parametrů (pro poziční parametry) do hranatých závorek. Název parametrů, které jsou poziční, jako je například parametr Name v následujícím příkladu, nemusí být zahrnuty do příkazu.
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
Pokud hodnota parametru může obsahovat více hodnot, například seznam názvů v parametru Name, přidejte dvojici hranatých závorek přímo za hodnotou parametru.
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
Pokud si uživatel může vybrat z parametrů nebo hodnot parametrů, jako je například parametr Typ, uzavřete volby do složených závorek a oddělte je výhradním symbolem OR(;).
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```
Pokud hodnota parametru musí používat specifické formátování, například uvozovky nebo závorky, zobrazí formát v syntaxi.
```
SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

Kódování XML diagramu syntaxe

Uzel syntaxe XML začíná hned po uzlu popisu, který končí značkou </maml:description>. Informace o shromažďování dat použitých v diagramu syntaxe naleznete v tématu Shromažďování informací o syntaxi.

Přidání uzlu syntaxe

Diagram syntaxe zobrazený v tématu nápovědy rutiny se generuje z dat v uzlu syntaxe XML. Uzel syntaxe je uzavřený do dvojice značek <command:syntax>. S každou sadou parametrů rutiny uzavřenou v dvojici <command:syntaxitem> značek. Počet <command:syntaxitem> značek, které můžete přidat, není nijak omezený.

Následující příklad ukazuje uzel syntaxe, který obsahuje uzly položek syntaxe pro dvě sady parametrů.

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

Přidání názvu rutiny do dat sady parametrů

Každá sada parametrů rutiny se zadává v uzlu položky syntaxe. Každý uzel položky syntaxe začíná dvojicí <maml:name> značek, které obsahují název rutiny.

Následující příklad obsahuje uzel syntaxe, který obsahuje uzly položek syntaxe pro dvě sady parametrů.

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

Přidání parametrů

Každý parametr přidaný do uzlu položky syntaxe se zadává v páru značek <command:parameter>. Potřebujete dvojici značek <command:parameter> pro každý parametr zahrnutý v sadě parametrů s výjimkou běžných parametrů, které poskytuje PowerShell.

Atributy počáteční značky <command:parameter> určují, jak se parametr zobrazuje v diagramu syntaxe. Informace o atributech parametrů naleznete v tématu Atributy parametru.

Poznámka:

Značka <command:parameter> podporuje podřízený prvek <maml:description>, jehož obsah se nikdy nezobrazí. Popisy parametrů jsou zadány v uzlu parametru XML. Abyste se vyhnuli nekonzistence mezi informacemi v položce syntaxe a uzlem parametru, vynechejte (<maml:description> nebo ponechte prázdné.

Následující příklad obsahuje uzel položky syntaxe pro sadu parametrů se dvěma parametry.

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>

Sdílet prostřednictvím