Cómo agregar ejemplos a un tema de Ayuda del cmdlet

Aspectos que debe saber sobre los ejemplos de la Ayuda de cmdlets

• Enumera todos los nombres de parámetro en el comando, incluso cuando los nombres de parámetro son opcionales. Esto ayuda al usuario a interpretar el comando fácilmente.

• Evite los alias y los nombres de parámetros parciales, aunque funcionen en PowerShell.

• En la descripción del ejemplo, explique la lógica para la construcción del comando. Explique por qué eligió parámetros y valores concretos y cómo usar variables.

• Si el comando usa expresiones, explíquelas en detalle.

• Si el comando usa propiedades y métodos de objetos, especialmente las propiedades que no aparecen en la pantalla predeterminada, use el ejemplo como una oportunidad para que el usuario le informe sobre el objeto.

Vistas de Ayuda que muestran ejemplos

Los ejemplos solo aparecen en las vistas Detallada y Completa de la Ayuda del cmdlet.

Agregar un nodo de ejemplos

En el siguiente xml se muestra cómo agregar un nodo Examples que contiene un único nodo de ejemplo. Agregue nodos de ejemplo adicionales para cada ejemplo que quiera incluir en el tema.

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

Agregar un título de ejemplo

En el siguiente XML se muestra cómo agregar un título para el ejemplo. El título se usa para establecer el ejemplo aparte de otros ejemplos. PowerShell usa un encabezado estándar que incluye un número de ejemplo secuencial.

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

Agregar caracteres anteriores

En el siguiente código XML se muestra cómo agregar caracteres, como el símbolo del sistema Windows PowerShell, que se muestran inmediatamente antes del comando de ejemplo (sin espacios que intervendrá). PowerShell usa el símbolo Windows PowerShell: 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>

Agregar el comando

El siguiente código XML muestra cómo agregar el comando real del ejemplo. Al agregar el comando, escriba el nombre completo (no use alias) de cmdlets y parámetros. Además, use caracteres en minúscula siempre que sea posible.

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

Agregar una descripción

En el xml siguiente se muestra cómo agregar una descripción para el ejemplo. PowerShell usa un único conjunto de <maml:para> etiquetas para la descripción, aunque se pueden usar varias <maml:para> etiquetas.

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

Agregar salida de ejemplo

En el siguiente XML se muestra cómo agregar la salida del comando. La información de los resultados del comando es opcional, pero en algunos casos resulta útil demostrar el efecto de usar parámetros específicos. PowerShell usa dos conjuntos de etiquetas en <maml:para> blanco para separar la salida del comando.

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