Lägga till exempel i ett cmdlet-hjälpavsnitt

  • Artikel

Saker att känna till om exempel i cmdlet-hjälpen

  • Lista alla parameternamn i kommandot, även om parameternamnen är valfria. Detta hjälper användaren att enkelt tolka kommandot.

  • Undvik alias och partiella parameternamn, även om de fungerar i PowerShell.

  • I exempelbeskrivningen förklarar du logiken för att bygga kommandot. Förklara varför du valde vissa parametrar och värden och hur du använder variabler.

  • Om kommandot använder uttryck ska du förklara dem i detalj.

  • Om kommandot använder egenskaper och metoder för objekt, särskilt egenskaper som inte visas i standardvisningen, använder du exemplet som en möjlighet att berätta för användaren om objektet.

Hjälpvyer som visar exempel

Exempel visas bara i detaljerade och fullständiga vyer för cmdlet-hjälpen.

Lägga till en exempelnod

Följande XML visar hur du lägger till en exempelnod som innehåller en enda exempelnod. Lägg till ytterligare exempelnoder för varje exempel som du vill ta med i ämnet.

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

Lägga till en exempelrubrik

Följande XML visar hur du lägger till en rubrik för exemplet. Rubriken används för att ange exemplet utöver andra exempel. PowerShell använder ett standardhuvud som innehåller ett sekventiellt exempelnummer.

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

Lägga till föregående tecken

Följande XML visar hur du lägger till tecken, till exempel Windows PowerShell prompt, som visas omedelbart före exempelkommandot (utan mellanliggande blanksteg). PowerShell använder Windows PowerShell prompten: 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>

Lägga till kommandot

Följande XML visar hur du lägger till det faktiska kommandot i exemplet. När du lägger till kommandot skriver du hela namnet (använd inte alias) för cmdlets och parametrar. Använd även gemener när det är möjligt.

<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>

Lägga till en beskrivning

Följande XML visar hur du lägger till en beskrivning av exemplet. PowerShell använder en enda uppsättning <maml:para> taggar för beskrivningen, även om <maml:para> flera taggar kan användas.

<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>

Lägga till exempelutdata

Följande XML visar hur du lägger till kommandots utdata. Informationen om kommandoresultat är valfri, men i vissa fall är det bra att demonstrera effekten av att använda specifika parametrar. PowerShell använder två uppsättningar tomma <maml:para> taggar för att separera kommandoutdata från kommandot.

<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>