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
Kezdje a parancsmag nevével.
SYNTAX Get-Tech
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.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.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
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]
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]
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]
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}]
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>
Visszajelzés
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Visszajelzés küldése és megtekintése a következőhöz: