Szintaxis hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhöz

Mielőtt elkezdi kódolni a szintaxisdiagram XML-fájlját a parancsmag súgófájljában, olvassa el ezt a szakaszt, hogy egyértelmű képet kapjon a meg kell adni kívánt adatok fajtáiról, például a paraméterattribútumokról, valamint arról, hogyan jelennek meg ezek az adatok a szintaxisdiagramon..

Paraméterattribútumok

  • Kötelező
    • Ha igaz, a paraméternek meg kell jelennie az összes olyan parancsban, amely a paraméterkészletet használja.
    • Ha hamis, a paraméter nem kötelező az összes olyan parancsban, amely a paraméterkészletet használja.
  • Pozíció
    • Ha a paraméter neve meg van adva, 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 position="1", a paraméter értékének a parancs első vagy egyetlen névtelen paraméterértékének kell lennie.
  • Folyamat bemenete
    • Ha igaz (ByValue), akkor a bemenetet a paraméterhez használhatja. A bemenet akkor is társítva van a paraméterhez ("kötött") 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 csak akkor próbálják a megfelelő típusra konvertálni a bemenetet, és a parancs sikertelen lesz, ha a típus nem konvertálható. Érték szerint egy paraméterkészletben csak egy paraméter társítható.
    • Ha true (ByPropertyName), akkor a bemenetet a paraméterhez használhatja. A bemenet azonban csak akkor van a paraméterhez társítva, ha a paraméter neve megegyezik a bemeneti objektum egyik tulajdonságának nevével. Ha például a paraméter neve , akkor a parancsmagnak átkért objektumok csak akkor vannak ehhez a paraméterhez társítva, ha az objektum Path rendelkezik path nevű tulajdonsággal.
    • Ha igaz (ByValue, ByPropertyName), akkor a bemenetet a tulajdonság neve vagy értéke alapján is át lehetvinni a paraméterbe. Érték szerint egy paraméterkészletben csak egy paraméter társítható.
    • Ha hamis, nem adhat át bemenetet erre a paraméterre.
  • Globbing (Globbing)
    • Ha igaz, a felhasználó által a paraméterértékhez be írt szöveg tartalmazhat helyettesítő karaktereket.
    • Ha hamis, a felhasználó által a paraméterértékhez be írt szöveg nem tartalmazhat helyettesítő karaktereket.

Paraméterérték-attribútumok

  • Kötelező
    • Ha igaz, a megadott értéket kell használni minden alkalommal, amikor a paramétert használja egy parancsban.
    • Ha hamis, a paraméter értéke nem kötelező. Az értékek általában csak akkor választhatók, ha egy paraméter számos érvényes értéke, például enumerált típus valamelyike.

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

A paraméter kötelező attribútuma azt jelzi, hogy a paramétert (és annak értékét) bele kell-e foglalni a parancsmag iniratekor. Ezzel szemben a paraméterérték kötelező attribútuma csak akkor használatos, ha a paraméter szerepel a parancsban. Azt jelzi, hogy az adott értéket a paraméterrel kell-e használni.

A helyőrző paraméterértékek és a literál paraméterértékek megadása általában nem kötelező, mert ezek egyike a paraméterrel használható számos értéknek.

Szintaxisinformációk gyűjtése

  1. Kezdje a parancsmag nevével.

    SYNTAX
        Get-Tech
    
  2. Listába sorolja a parancsmag összes paraméterét. Írjon be egy kötőjelet ( - ) (ASCII 45) minden paraméternév előtt. Válassza szét a paramétereket paraméterkészletekbe (előfordulhat, hogy egyes parancsmagok csak egy paraméterkészletet használnak). Ebben a példában a Get-Tech parancsmag két paraméterkészletből áll.

    SYNTAX
        Get-Tech -name -type
        Get-Tech -ID -list -type
    

    Indítsa el az egyes paraméterkészleteket a parancsmag nevével.

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

    Minden paraméterkészlethez először sorolja fel az egyedi paraméterét, kivéve, ha vannak olyan pozícióparaméterek, amelyeknél először meg kell jelennie. Az előző példában a Name és az ID paraméterek a két paraméterkészlet egyedi paraméterei (minden paraméterkészletnek egy olyan paraméterrel kell lennie, amely egyedi az adott paraméterkészlethez). Így a felhasználók könnyebben azonosítják a paraméterkészlethez szükséges paramétert.

    Sorolja fel a paramétereket abban a sorrendben, ahogy a parancsban meg kell jelenni. Ha a sorrend nem számít, listába sorolja össze a kapcsolódó paramétereket, vagy először listába sorolja fel a leggyakrabban használt paramétereket.

    Ne hagyja ki a WhatIf és a Confirm paramétereket, ha a parancsmag támogatja a ShouldProcess függvényt.

    A szintaxisdiagramon ne sorolja fel a gyakori paramétereket (például Részletes, Hibakeresés és ErrorAction). A Get-Help parancsmag hozzáadja ezt az információt, amikor megjelenik a Súgó témakör.

  3. Adja hozzá a paraméterértékeket. A PowerShellben a paraméterértékeket a .NET-típusuk képviseli. A típusnév rövidíthető is, például a "string" (sztring) a System.String sztringhez.

    SYNTAX
        Get-Tech -name string -type basic advanced
        Get-Tech -ID int -list -type basic advanced
    

    A típusok rövidítése, ha a jelentése egyértelmű, például sztring a System.String és az int a System.Int32 esetében.

    Sorolja fel az enumerálások összes értékét, például az előző példában található paramétert, amely alapszintű vagy -type speciális lehet.

    A kapcsolóparaméterek (például -list az előző példában) nem tartalmaznak értékeket.

  4. Szögletes zárójeleket adhat a helyőrző paraméterek értékeihez a literálok paraméterértékeivel összehasonlítva.

    SYNTAX
        Get-Tech -name <string> -type basic advanced
        Get-Tech -ID <int> -list -type basic advanced
    
  5. A választható paramétereket és a valejüket szögletes zárójelben kell megadni.

    SYNTAX
        Get-Tech -name <string> [-type basic advanced]
        Get-Tech -ID <int> [-list] [-type basic advanced]
    
  6. A választható paraméterek neveit (pozícióparaméterek esetén) szögletes zárójelek közé helyezze. A pozíciós paraméterek nevét (például a következő példában a Name paramétert) nem kell szerepeltetni a parancsban.

    SYNTAX
        Get-Tech [-name] <string> [-type basic advanced]
        Get-Tech -ID <int> [-list] [-type basic advanced]
    
  7. Ha egy paraméterérték több értéket is tartalmazhat, például a Name paraméterben szereplő nevek listáját, vegyen fel egy pár szögletes zárójelet közvetlenül a paraméter értéke után.

    SYNTAX
        Get-Tech [-name] <string[]> [-type basic advanced]
        Get-Tech -ID <int[]> [-list] [-type basic advanced]
    
  8. Ha a felhasználó paraméterek vagy paraméterértékek, például a Típus paraméter közül választhat, a választási lehetőségeket 3. szögletes zárójelek közé zárja, és válassza el őket az exkluzív VAGY szimbólummal (;).

    SYNTAX
        Get-Tech [-name] <string[]> [-type {basic | advanced}]
        Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
    
  9. Ha a paraméter értékének meghatározott formázást kell használnia, például idézőjeleket vagy zárójeleket, akkor a szintaxisban mutassa a formátumot.

    SYNTAX
        Get-Tech [-name] <"string[]"> [-type {basic | advanced}]
        Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
    

A szintaxisdiagram XML-fájl kódolása

Az XML szintaxis-csomópontja közvetlenül a leíró csomópont után kezdődik, amely a címkével </maml:description> végződik. További információ a szintaxisdiagramban használt adatok gyűjtéséről: A szintaxissal kapcsolatos információk összegyűjtése.

Szintaxiscsomópont hozzáadása

A parancsmag súgótémakörében megjelenő szintaxisdiagram az XML szintaxiscsomópontjának adataiból jön létre. A szintaxiscsomópont két címke között <command:syntax> található. A parancsmag minden paraméterkészlete egy címkepárba <command:syntaxitem> van adva. A felvehető címkék száma nincs <command:syntaxitem> korlátozva.

Az alábbi példa egy szintaxis-csomó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-adatokhoz

A parancsmag minden paraméterkészlete egy szintaxiselem-csomópontban van megadva. Minden szintaktikai elem csomópontja egy címkepárból indul ki, amelyek tartalmazzák a <maml:name> parancsmag nevét.

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

<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 adott minden paraméter egy címkepáron belül van <command:parameter> megadva. A paraméterkészletben szereplő minden paraméterhez szüksége lesz egy címkepárra, a PowerShell által biztosított közös <command:parameter> paraméterek kivételével.

A nyitó címke attribútumai határozzák meg, hogy a paraméter hogyan jelenik meg <command:parameter> a szintaxisdiagramon. A paraméterattribútumokkal kapcsolatos információkért lásd: Paraméterattribútumok.

Megjegyzés

A <command:parameter> címke olyan gyermekelemet <maml:description> támogat, amelynek tartalma soha nem jelenik meg. A paraméterek leírása az XML paramétercsomópontján van megadva. A szintaxiselemben és a paramétercsomópontban található információk közötti inkonzisztencia elkerülése érdekében hagyja üresen a ( <maml:description> mezőt.

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>