Szintaxis hozzáadása parancsmag súgótémakörhöz

Megjegyzés

Az XML-alapú súgó manuális készítése nagyon nehéz. A PlatyPS modul lehetővé teszi, hogy segítséget írjon a Markdownban, majd XML-alapú súgóvá konvertálja. Ez sokkal egyszerűbbé teszi a súgó írását és karbantartását. PlatyPS is létrehozhatja a Frissíthető súgócsomagokat. További információ: Xml-alapú súgó létrehozása a PlatyPShasználatával.

Mielőtt elkezdené kódolni a szintaxisdiagram XML-kódját a parancsmag súgófájljában, olvassa el ezt a szakaszt, hogy egyértelmű képet kapjon arról, hogy milyen típusú adatokat kell megadnia, például a paraméterattribútumokat, és hogyan jelennek meg az adatok a szintaxisdiagramon.

Paraméterattribútumok

Kötelező
- Ha igaz, a paraméternek a paraméterkészletet használó összes parancsban meg kell jelennie.
- Ha hamis, a paraméter nem kötelező minden olyan parancsban, amely a paraméterkészletet használja.
Pozíció
- Ha el van nevezve, a paraméternév megadása kötelező.
- Pozíció esetén a paraméter neve nem kötelező. Ha nincs megadva, a paraméter értékének a parancsban megadott helyen kell lennie. Ha például az érték pozíció="1", a paraméterértéknek a parancs első vagy csak névtelen paraméterértékének kell lennie.
Folyamatbemenet
- Ha igaz (ByValue), a paraméterbe beírhatja a bemenetet. A bemenet akkor is társítva van a paraméterrel ,,ha a tulajdonság neve és az objektumtípus nem egyezik a várt típussal. A PowerShell paraméterkötési összetevői megpróbálják a bemenetet a megfelelő típusra konvertálni, és csak akkor hiúsul meg a parancs, ha a típus nem konvertálható. Egy paraméterkészletben csak egy paraméter társítható érték szerint.
- Ha igaz (ByPropertyName), akkor a paraméterbe beírhatja a bemenetet. A bemenet azonban csak akkor van társítva a paraméterhez, ha a paraméter neve megegyezik a bemeneti objektum egyik tulajdonságának nevével. Ha például a paraméter neve Path, akkor a parancsmaghoz tartozó objektumok csak akkor lesznek társítva ehhez a paraméterhez, ha az objektumnak van egy elérési útja nevű tulajdonsága.
- Ha igaz (ByValue, ByPropertyName), akkor a paraméter bemenetét tulajdonságnév vagy érték alapján is beírhatja. Egy paraméterkészletben csak egy paraméter társítható érték szerint.
- Ha hamis, nem tud bemenő csövet adni ehhez a paraméterhez.
Globbing
- Ha igaz, a paraméterértékhez a felhasználó által beírt szöveg tartalmazhat helyettesítő karaktereket.
- Ha hamis, a paraméterértékhez a felhasználó által beírt szöveg nem tartalmazhat helyettesítő karaktereket.

Paraméter értékattribútumai

Kötelező
- Ha igaz, akkor a megadott értéket kell használni, amikor a paramétert egy parancsban használja.
- Ha hamis, a paraméter értéke nem kötelező. Egy érték általában csak akkor választható, ha egy paraméter több érvényes értékének egyike, például számbavételes típusban.

A paraméterérték Kötelező attribútuma eltér a paraméter Kötelező attribútumától.

A paraméter kötelező attribútuma azt jelzi, hogy a paramétert (és annak értékét) tartalmaznia kell-e a parancsmag meghívásakor. Ezzel szemben a paraméterérték szükséges attribútuma csak akkor használatos, ha a paraméter szerepel a parancsban. Azt jelzi, hogy az adott értéket használni kell-e a paraméterrel.

A helyőrzők paraméterértékei általában kötelezőek, a konstans paraméterértékek pedig nem kötelezőek, mivel ezek a paraméterrel használható számos érték egyike.

Szintaxisadatok gyűjtése

Kezdje a parancsmag nevével.
```
SYNTAX
    Get-Tech
```
A parancsmag összes paraméterének felsorolása. Minden paraméternév előtt írjon be egy kötőjelet (-). Válassza el a paramétereket paraméterkészletekre (egyes parancsmagok csak egy paraméterkészlettel rendelkezhetnek). Ebben a példában a Get-Tech parancsmag két paraméterkészlettel rendelkezik.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Indítsa el az egyes paramétereket a parancsmag nevével.

Először adja meg az alapértelmezett paraméterkészletet. Az alapértelmezett paramétert a parancsmagosztály adja meg.

Minden paraméterkészlethez először sorolja fel az egyedi paramétert, kivéve, ha vannak olyan pozícióparaméterek, amelyeknek először meg kell jelenniük. Az előző példában a Név és azonosító paraméterek a két paraméterkészlet egyedi paraméterei (minden paraméterkészletnek egy olyan paramétert kell tartalmaznia, amely egyedi az adott paraméterkészlethez). Így a felhasználók könnyebben azonosíthatják, hogy milyen paramétert kell megadniuk a paraméterkészlethez.

A paraméterek felsorolása a parancsban megjelenítendő sorrendben. Ha a sorrend nem számít, a kapcsolódó paramétereket együtt listázhatja, vagy először listázhatja a leggyakrabban használt paramétereket.

Ügyeljen arra, hogy felsorolja a WhatIf és a Confirm paramétereket, ha a parancsmag támogatja a ShouldProcess parancsmagot.

A szintaxisdiagramban ne sorolja fel a gyakori paramétereket (például Részletes, Hibakeresés és ErrorAction). A Get-Help parancsmag hozzáadja ezeket az információkat a súgótémakör megjelenítésekor.
Adja hozzá a paraméterértékeket. A PowerShellben a paraméterértékeket a .NET-típusuk jelöli. A típusnév azonban rövidíthető, például a System.String sztringje.
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
Rövidített típusok, ha jelentésük egyértelmű, például System.String és intSystem.Int32.

Listázhatja az enumerálások összes értékét, például az előző példában szereplő -Type paramétert, amely beállítható alapszintű vagy speciális.

A kapcsolóparaméterek, például az előző példában -List, nem rendelkeznek értékekkel.
Szögletes zárójelek hozzáadása helyőrző paraméterértékekhez a literál paraméterértékekhez képest.
```
SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced
```

Mellékelje az opcionális paramétereket és azok értékeit szögletes zárójelek közé.

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

Mellékelje az opcionális paraméterek nevét (a pozícióparaméterekhez) szögletes zárójelek közé. A helymeghatározó paraméterek nevét, például a következő példában szereplő Név paramétert nem kell szerepeltetni a parancsban.
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
Ha egy paraméterérték több értéket is tartalmazhat, például egy névlistát a Név paraméterben, adjon hozzá egy szögletes zárójelet közvetlenül a paraméterérték után.
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
Ha a felhasználó választhat paraméterek vagy paraméterértékek közül, például a Típus paraméter közül, a lehetőségeket szögletes zárójelek közé kell foglalnia, és elválaszthatja őket a kizárólagos VAGY szimbólummal (;).
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```
Ha a paraméterértéknek adott formázást kell használnia, például idézőjeleket vagy zárójeleket, akkor a szintaxisban jelenítse meg a formátumot.
```
SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

A szintaxisdiagram XML-fájljának kódolása

Az XML szintaxiscsomópontja közvetlenül a leírási csomópont után kezdődik, amely a </maml:description> címkével végződik. A szintaxisdiagramban használt adatok gyűjtéséről további információt Szintaxisadatok gyűjtésecímű témakörben talál.

Szintaxiscsomópont hozzáadása

A súgótémakörben megjelenő szintaxisdiagram az XML szintaxiscsomópontjának adataiból jön létre. A szintaxiscsomópont <command:syntax> címkék párjában található. A parancsmag minden paraméterkészletét <command:syntaxitem> címkék párja tartalmazza. Nincs korlátozva a felvehető <command:syntaxitem> címkék száma.

Az alábbi példa egy szintaxiscsomópontot mutat be, amely két paraméterkészlet szintaxiselem-csomópontjaival rendelkezik.

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

A parancsmag nevének hozzáadása a paraméterkészlet adataihoz

A parancsmag minden paraméterkészlete egy szintaxiselem-csomópontban van megadva. Minden szintaxiselem-csomópont egy <maml:name> címkével kezdődik, amelyek tartalmazzák a parancsmag nevét.

Az alábbi példa egy szintaxiscsomópontot tartalmaz, amely két paraméterkészlet szintaxiselem-csomópontjaival rendelkezik.

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

Paraméterek hozzáadása

A szintaxiselem-csomóponthoz hozzáadott összes paraméter <command:parameter> címkén belül van megadva. Szükség van egy pár <command:parameter> címkére a paraméterkészlet minden paraméteréhez, kivéve a PowerShell által biztosított gyakori paramétereket.

A nyitó <command:parameter> címke attribútumai határozzák meg, hogyan jelenik meg a paraméter a szintaxisdiagramban. A paraméterattribútumokról további információt Paraméterattribútumokcímű témakörben talál.

Megjegyzés

A <command:parameter> címke olyan gyermekelemet támogat, <maml:description> amelynek tartalma soha nem jelenik meg. A paraméterleírások az XML paramétercsomópontjában vannak megadva. A szintaxiselem és a paramétercsomópont információi közötti ellentmondások elkerülése érdekében hagyja ki a (<maml:description> vagy hagyja üresen.

Az alábbi példa egy szintaxiselem-csomópontot tartalmaz egy két paramétert tartalmazó paraméterkészlethez.

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

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-03-25