Come aggiungere esempi a un argomento della Guida sui cmdletHow to Add Examples to a Cmdlet Help Topic

Informazioni sugli esempi nella Guida dei cmdletThings to Know about Examples in Cmdlet Help

  • Elencare tutti i nomi di parametro nel comando, anche quando i nomi dei parametri sono facoltativi.List all of the parameter names in the command, even when the parameter names are optional. Questo consente all'utente di interpretare il comando con facilità.This helps the user to interpret the command easily.

  • Evitare gli alias e i nomi di parametro parziali, anche se funzionano in PowerShell.Avoid aliases and partial parameter names, even though they work in PowerShell.

  • Nella descrizione dell'esempio, spiegare il razionale per la costruzione del comando.In the example description, explain the rational for the construction of the command. Spiegare il motivo per cui si sono scelti parametri e valori specifici e come usare le variabili.Explain why you chose particular parameters and values, and how you use variables.

  • Se il comando usa espressioni, spiegarle in dettaglio.If the command uses expressions, explain them in detail.

  • Se il comando USA proprietà e metodi di oggetti, in particolare le proprietà che non vengono visualizzate nella visualizzazione predefinita, usare l'esempio come opportunità per informare l'utente sull'oggetto.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.

Viste della guida che visualizzano esempiHelp Views that Display Examples

Gli esempi vengono visualizzati solo nella visualizzazione dettagliata e completa della guida del cmdlet.Examples appear only in the Detailed and Full views of cmdlet Help.

Aggiunta di un nodo esempiAdding an Examples Node

Nel codice XML seguente viene illustrato come aggiungere un nodo esempi contenente un singolo nodo di esempio .The following XML shows how to add an Examples node that contains a single Example node. Aggiungere altri nodi di esempio per ogni esempio che si desidera includere nell'argomento.Add additional example nodes for each examples you want to include in the topic.

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

Aggiunta di un titolo di esempioAdding an Example Title

Nel codice XML seguente viene illustrato come aggiungere un titolo per l'esempio.The following XML shows how to add a title for the example. Il titolo viene usato per impostare l'esempio oltre ad altri esempi.The title is used to set the example apart from other examples. PowerShell usa un'intestazione standard che include un numero di esempio sequenziale.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>

Aggiunta di caratteri precedentiAdding Preceding Characters

Nel codice XML seguente viene illustrato come aggiungere caratteri, ad esempio il prompt di Windows PowerShell, che vengono visualizzati immediatamente prima del comando di esempio (senza spazi intermedi).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). PowerShell usa il prompt di Windows PowerShell: 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>

Aggiunta del comandoAdding the Command

Nel codice XML seguente viene illustrato come aggiungere il comando effettivo dell'esempio.The following XML shows how to add the actual command of the example. Quando si aggiunge il comando, digitare l'intero nome (non usare alias) di cmdlet e parametri.When adding the command, type the entire name (do not use alias) of cmdlets and parameters. Inoltre, quando possibile, utilizzare caratteri minuscoli.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>

Aggiunta di una descrizioneAdding a Description

Nel codice XML seguente viene illustrato come aggiungere una descrizione per l'esempio.The following XML shows how to add a description for the example. PowerShell usa un singolo set di <maml:para> tag per la descrizione, anche se <maml:para> è possibile usare più tag.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>

Aggiunta dell'output di esempioAdding Example Output

Nel codice XML seguente viene illustrato come aggiungere l'output del comando.The following XML shows how to add the output of the command. Le informazioni sui risultati del comando sono facoltative, ma in alcuni casi è utile illustrare l'effetto dell'utilizzo di parametri specifici.The command results information is optional, but in some cases it is helpful to demonstrate the effect of using specific parameters. PowerShell usa due set di <maml:para> tag vuoti per separare l'output del comando dal comando.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>