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

  1. 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>
    
  2. 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>
    
  3. 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.

  4. 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>
    
  5. 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>
    
  6. 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>
    
  7. 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>
    
  8. 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>
    
  9. 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>