Paraméteradatok hozzáadása
Ez a szakasz a parancsmagokkal kapcsolatos súgótémakör PARAMETERS szakaszában megjelenő tartalom hozzáadását ismerteti. A súgótémakör PARAMETERS szakasza felsorolja a parancsmag egyes paramétereit, és részletes leírást ad az egyes paraméterekről.
A PARAMETERS szakasz tartalmának konzisztensnek kell lennie a súgótémakör SZINTAXIS szakaszának tartalmával. A Súgó szerzője feladata, hogy a Szintaxis és a Paraméterek csomópont is hasonló XML-elemeket tartalmaz.
Megjegyzés
A súgófájl teljes megtekintéséhez nyissa meg a PowerShell telepítési könyvtárában dll-Help.xml
található fájlok valamelyikét. A fájl például több PowerShell-parancsmag tartalmát Microsoft.PowerShell.Commands.Management.dll-Help.xml
is tartalmazza.
Paraméterek hozzáadása
Nyissa meg a parancsmag súgófájlját, és keresse meg a parancscsomópontot a dokumentálni kívánt parancsmaghoz. Ha új parancsmagot ad hozzá, létre kell hoznia egy új parancscsomópontot. A súgófájl minden parancsmaghoz tartalmazni fog egy parancscsomópontot, amely számára súgótartalmat biztosít. Példa egy üres parancscsomópontra.
<command:command> </command:command>
A parancscsomóponton belül keresse meg a Leírás csomópontot, és adjon hozzá egy Parameters (Paraméterek) csomópontot az alább látható módon. Csak egy Paraméter csomópont engedélyezett, és azonnal követnie kell a Szintaxis csomópontot.
<command:command> <command:details></command:details> <maml:description></maml:description> <command:syntax></command:syntax> <command:parameters> </command:parameters> </command:command>
A Paraméterek csomóponton belül adjon hozzá egy Paraméter csomópontot a parancsmag minden paramétere számára az alább látható módon.
Ebben a példában három paraméterhez adunk hozzá egy Paraméter csomópontot.
<command:parameters> <command:parameter></command:parameter> <command:parameter></command:parameter> <command:parameter></command:parameter> </command:parameters>
Mivel ezek ugyanazok az XML-címkék, amelyek a Szintaxis csomópontban használatosak, és mivel az itt megadott paramétereknek meg kell egyezniük a Szintaxis csomópont által megadott paraméterekkel, átmásolhatja a Paraméter csomópontokat a Szintaxis csomópontból, és beillesztheti őket a Paraméterek csomópontba. A Paraméter csomópontnak azonban csak egy példányát másolja, még akkor is, ha a paraméter több paraméterkészletben van megadva a szintaxisban.
Minden paramétercsomóponthoz állítsa be az egyes paraméterek jellemzőit meghatározó attribútumértékeket. Ezek az attribútumok a következők: kötelező, globbing, pipelineinput és pozíció.
<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>
Minden paramétercsomóponthoz adja hozzá a paraméter nevét. Példa a Paraméter csomóponthoz hozzáadott paraméternévre.
<command:parameters> <command:parameter required="true" globbing="true" pipelineInput="false" position="named"> <maml:name> Add parameter name... </maml:name> </command:parameter> </command:parameters>
Minden paramétercsomóponthoz adja meg a paraméter leírását. Példa a Paraméter csomóponthoz hozzáadott paraméterleírásra.
<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>
Minden paramétercsomóponthoz adja hozzá a paraméter .NET-típusát. Megjelenik a paraméter típusa a paraméter nevével együtt.
Példa a Paraméter csomóponthoz hozzáadott .NET-típusra.
<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>
Minden paramétercsomóponthoz adja hozzá a paraméter alapértelmezett értékét. A rendszer a következő mondatot ad hozzá a paraméter leíráshoz a tartalom megjelenítésekor: DefaultValue az alapértelmezett érték.
Példa arra, hogy a paraméter alapértelmezett értéke hozzá van adva a Paraméter csomóponthoz.
<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>
Minden több értékkel rendelkező paraméterhez adjon hozzá egy possibleValues csomópontot.
Az alábbi példa egy possibleValues csomópontot mutat be, amely két lehetséges értéket határoz meg a paraméterhez
<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>
Paraméterek hozzáadásakor az íme néhány dolog, amit meg kell jegyezni.
A paraméter attribútumai nem jelennek meg a parancsmag súgótémakörének összes nézetében. Ezek azonban a paraméter leírását követő táblázatban jelennek meg, amikor a felhasználó a témakör Full ( ) vagy
Get-Help <cmdletname> -Full
Parameter (Get-Help <cmdletname> -Parameter
) nézetét kéri.A paraméter leírása a parancsmagokkal kapcsolatos súgótémakör egyik legfontosabb része. A leírásnak rövidnek és alaposnak kell lennie. Ne feledje, hogy ha a paraméter leírása túl hosszú, például amikor két paraméter kommunikál egymással, további tartalmakat adhat hozzá a parancsmag súgótémakörének NOTES szakaszában.
A paraméter leírása két információtípust biztosít.
Mit tesz a parancsmag a paraméter használatakor?
A paraméter jogi értéke.
Mivel a paraméterértékek .NET-objektumokként vannak kifejezve, a felhasználóknak több információra van szükségük ezekről az értékekről, mint egy hagyományos parancssori súgóban. Mondja el a felhasználónak, hogy milyen típusú adatok elfogadására lett tervezve a paraméter, és tartalmaz példákat.
A paraméter alapértelmezett értéke az az érték, amely akkor használatos, ha a paraméter nincs megadva a parancssorban. Vegye figyelembe, hogy az alapértelmezett érték nem kötelező, és nem szükséges egyes paraméterekhez, például a kötelező paraméterekhez. Azonban a legtöbb választható paraméterhez meg kell adnia egy alapértelmezett értéket.
Az alapértelmezett érték segít a felhasználónak megérteni, hogy milyen hatással van a paraméter használatának mellőre. Írja le az alapértelmezett értéket egészen pontosan, például az "Aktuális könyvtár" vagy a "PowerShell telepítési könyvtárat ( )" egy $PSHOME
választható elérési úthoz. Az alapértelmezett értéket leíró mondatot is írhat, például a PassThru paraméterhez használt következő mondatot: "Ha a PassThru nincs megadva, a parancsmag nem ad át objektumokat a folyamatnak." Továbbá, mivel az érték az Alapértelmezett érték mezőnévvel szemben jelenik meg, a bejegyzésben nem kell szerepeltetni az "alapértelmezett érték" kifejezést.
A paraméter alapértelmezett értéke nem jelenik meg a parancsmag súgótémakörének összes nézetében. A paraméter leírása után azonban megjelenik egy táblázatban (a paraméterattribútumokkal együtt), amikor a felhasználó a témakör Full ( ) vagy Parameter ( ) nézetét Get-Help <cmdletname> -Full
Get-Help <cmdletname> -Parameter
kéri.
Az alábbi XML-fájlban a csomóponthoz <dev:defaultValue>
hozzáadott címkék egy párja <command:parameter>
látható.
Figyelje meg, hogy az alapértelmezett érték közvetlenül a záró címke (ha a paraméter értéke meg van adva) vagy a paraméter leírásának záró </command:parameterValue>
</maml:description>
címkéje után következik. név.
<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>
Értékek hozzáadása enumerált típusokhoz
Ha a paraméter több, enumerált típusú értékkel vagy értékkel rendelkezik, opcionális csomópontot is <dev:possibleValues>
használhat. Ez a csomópont lehetővé teszi több érték nevének és leírásának megadását.
Vegye figyelembe, hogy az enumerált értékek leírásai nem jelennek meg a parancsmag által megjelenített alapértelmezett súgónézetek egyikében sem, de más súgómegjelenítők is megjeleníthetnek ilyen tartalmat a Get-Help
nézetükön.
Az alábbi XML-fájlban egy <dev:possibleValues>
két értékkel megadott csomópont látható.
<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>
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: