Példák hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhözHow to Add Examples to a Cmdlet Help Topic

Tudnivalók a parancsmag súgójában található példákrólThings to Know about Examples in Cmdlet Help

  • Listázza az összes paraméter nevét a parancsban, még akkor is, ha a paraméterek neve nem kötelező.List all of the parameter names in the command, even when the parameter names are optional. Ez segít a felhasználónak a parancs egyszerű értelmezésében.This helps the user to interpret the command easily.

  • Kerülje az aliasok és a részleges paraméterek nevét, még akkor is, ha azok a PowerShellben működnek.Avoid aliases and partial parameter names, even though they work in PowerShell.

  • A példában szereplő leírásban ismertesse a parancs felépítésének indoklását.In the example description, explain the rational for the construction of the command. Magyarázza el, miért választott ki bizonyos paramétereket és értékeket, és hogyan használja a változókat.Explain why you chose particular parameters and values, and how you use variables.

  • Ha a parancs kifejezéseket használ, részletesen ismertesse őket.If the command uses expressions, explain them in detail.

  • Ha a parancs az objektumok tulajdonságait és metódusait használja, különösen azokat a tulajdonságokat, amelyek nem jelennek meg az alapértelmezett megjelenítésben, használja a példát arra, hogy az objektumról tájékoztassa a felhasználót.If the command uses properties and methods of objects, especially properties that do not appear in the default display, use the example as an opportunity tell the user about the object.

Példákat megjelenítő Súgó nézetekHelp Views that Display Examples

A példák csak a parancsmag súgójának részletes és teljes nézeteiben jelennek meg.Examples appear only in the Detailed and Full views of cmdlet Help.

Példa csomópont hozzáadásáraAdding an Examples Node

Az alábbi XML-kód azt mutatja be, hogyan adhat hozzá egy példa csomópontot tartalmazó, példaként szolgáló csomópontot .The following XML shows how to add an Examples node that contains a single Example node. Adja hozzá a további példa csomópontokat a témakörbe foglalni kívánt példákhoz.Add additional example nodes for each examples you want to include in the topic.

<command:examples>
  <command:example>
  </command:example>
</command:examples>

Példa címének hozzáadásaAdding an Example Title

Az alábbi XML-kód azt mutatja be, hogyan adhat hozzá egy címet a példához.The following XML shows how to add a title for the example. A cím a példa más példákon kívüli beállítására szolgál.The title is used to set the example apart from other examples. A PowerShell egy szabványos fejlécet használ, amely egy szekvenciális példát tartalmaz.PowerShell uses a standard header that includes a sequential example number.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
  </command:example>
</command:examples>

Előző karakterek hozzáadásaAdding Preceding Characters

Az alábbi XML-kód azt mutatja be, hogyan adhat hozzá olyan karaktereket (például a Windows PowerShell-parancssort), amelyek közvetlenül a példa parancs előtt jelennek meg (beavatkozó szóközök nélkül).The following XML shows how to add characters, such as the Windows PowerShell prompt, that are displayed immediately before the example command (without any intervening spaces). A PowerShell a Windows PowerShell-parancssort használja: C:\PS> .PowerShell uses the Windows PowerShell prompt: C:\PS>.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
</command:example>
</command:examples>

A parancs hozzáadásaAdding the Command

Az alábbi XML-kód azt mutatja be, hogyan lehet hozzáadni a példa tényleges parancsát.The following XML shows how to add the actual command of the example. A parancs hozzáadásakor írja be a parancsmagok és paraméterek teljes nevét (ne használjon aliast).When adding the command, type the entire name (do not use alias) of cmdlets and parameters. Ha lehetséges, használjon kisbetűs karaktereket is.Also, use lowercase characters whenever possible.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
</command:example>
</command:examples>

Leírás hozzáadásaAdding a Description

A következő XML-kód azt mutatja be, hogyan adhat hozzá leírást a példához.The following XML shows how to add a description for the example. A PowerShell egyetlen <maml:para> címkét használ a leíráshoz, annak ellenére, hogy több <maml:para> címke is használható.PowerShell uses a single set of <maml:para> tags for the description, even though multiple <maml:para> tags can be used.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
    </dev:remarks>
</command:example>
</command:examples>

Példa kimenet hozzáadásaAdding Example Output

Az alábbi XML-kód a parancs kimenetének hozzáadását mutatja be.The following XML shows how to add the output of the command. A parancs eredményének információi nem kötelezőek, de bizonyos esetekben hasznos lehet bemutatni az adott paraméterek használatának hatását.The command results information is optional, but in some cases it is helpful to demonstrate the effect of using specific parameters. A PowerShell két üres címkét használ a parancs <maml:para> kimenetének a parancsból való elkülönítéséhez.PowerShell uses two sets of blank <maml:para> tags to separate the command output from the command.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
      <maml:para></maml:para>
      <maml:para></maml:para>
      <maml:para> command output </maml:para>
</dev:remarks>
</command:example>
</command:examples>