Cómo agregar ejemplos a un tema de ayuda de cmdlet

Nota

La creación manual de ayuda basada en XML es muy difícil. El módulo PlatyPS le permite escribir ayuda en Markdown y luego convertirla en ayuda basada en XML. Esto hace que sea mucho más fácil escribir y mantener la ayuda. PlatyPS también puede crear paquetes de ayuda actualizables para usted. Para obtener más información, consulte Crear ayuda basada en XML utilizando PlatyPS.

Cosas que debe saber sobre los ejemplos en la ayuda de cmdlet

Enumere todos los nombres de los parámetros en el comando, incluso cuando los nombres de los parámetros sean opcionales. Esto ayuda al usuario a interpretar el comando fácilmente.
Evite alias y nombres de parámetros parciales, aunque funcionen en PowerShell.
En la descripción del ejemplo, explique el fundamento de la construcción del comando. Explique por qué eligió parámetros y valores particulares y cómo utiliza las variables.
Si el comando utiliza expresiones, explíquelas en detalle.
Si el comando usa propiedades y métodos de objetos, especialmente propiedades que no aparecen en la visualización predeterminada, use el ejemplo como una oportunidad para informarle al usuario 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

El siguiente XML muestra cómo agregar un nodo Ejemplos que contiene un único nodo Ejemplo. Agregue nodos de ejemplo adicionales para cada ejemplo que desee incluir en el tema.

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

Agregar un título de ejemplo

El siguiente XML muestra cómo agregar un título para el ejemplo. El título se utiliza para diferenciar el ejemplo 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

El siguiente XML muestra cómo agregar caracteres, como el símbolo del sistema de Windows PowerShell, que se muestran inmediatamente antes del comando de ejemplo (sin espacios intermedios). PowerShell utiliza el mensaje de Windows PowerShell: C:\PS>.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:introduction>
      <maml:para>C:\PS></maml:para>
    </maml:introduction>
</command:example>
</command:examples>

Agregando el comando

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

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

Agregar una descripción

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

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:introduction>
      <maml:para>C:\PS></maml:para>
    </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

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

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:introduction>
      <maml:para>C:\PS></maml:para>
    </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>