Voorbeelden toevoegen aan een Help-onderwerp voor cmdlets

Wat u moet weten over voorbeelden in cmdlet Help

• Vermeld alle parameternamen in de opdracht, zelfs wanneer de parameternamen optioneel zijn. Hierdoor kan de gebruiker de opdracht eenvoudig interpreteren.

• Vermijd aliassen en gedeeltelijke parameternamen, ook al werken ze in PowerShell.

• Leg in de voorbeeldbeschrijving de rationale uit voor de constructie van de opdracht. Leg uit waarom u bepaalde parameters en waarden hebt gekozen en hoe u variabelen gebruikt.

• Als de opdracht gebruikmaakt van expressies, leg deze dan uitgebreid uit.

• Als de opdracht gebruikmaakt van eigenschappen en methoden van objecten, met name eigenschappen die niet worden weergegeven in de standaardweergave, gebruikt u het voorbeeld als een kans om de gebruiker te vertellen over het object.

Help-weergaven met voorbeelden

Voorbeelden worden alleen weergegeven in de gedetailleerde en volledige weergaven van de Help-cmdlet.

Een voorbeeld-knooppunt toevoegen

De volgende XML laat zien hoe u een knooppunt Voorbeelden toevoegt dat één voorbeeld-knooppunt bevat. Voeg extra voorbeeldknooppunten toe voor elke voorbeelden die u in het onderwerp wilt opnemen.

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

Een voorbeeldtitel toevoegen

De volgende XML laat zien hoe u een titel voor het voorbeeld toevoegt. De titel wordt gebruikt om het voorbeeld te onderscheiden van andere voorbeelden. PowerShell maakt gebruik van een standaardheader die een sequentieel voorbeeldnummer bevat.

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

Voorgaande tekens toevoegen

De volgende XML laat zien hoe u tekens toevoegt, zoals de Windows PowerShell prompt, die direct vóór de voorbeeldopdracht worden weergegeven (zonder tussenliggende spaties). PowerShell maakt gebruik van Windows PowerShell opdrachtprompt: 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>

De opdracht toevoegen

De volgende XML laat zien hoe u de werkelijke opdracht van het voorbeeld toevoegt. Wanneer u de opdracht toevoegt, typt u de volledige naam (gebruik geen alias) van cmdlets en parameters. Gebruik waar mogelijk ook kleine letters.

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

Een beschrijving toevoegen

De volgende XML laat zien hoe u een beschrijving voor het voorbeeld toevoegt. PowerShell gebruikt één set <maml:para> tags voor de beschrijving, zelfs als er meerdere <maml:para> tags kunnen worden gebruikt.

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

Voorbeelduitvoer toevoegen

De volgende XML laat zien hoe u de uitvoer van de opdracht toevoegt. De informatie over de opdrachtresultaten is optioneel, maar in sommige gevallen is het handig om het effect van het gebruik van specifieke parameters te demonstreren. PowerShell gebruikt twee sets lege <maml:para> tags om de opdrachtuitvoer van de opdracht te scheiden.

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