Cómo agregar ejemplos a un tema de Ayuda del cmdletHow to Add Examples to a Cmdlet Help Topic

Aspectos que se deben conocer sobre los ejemplos de la ayuda de cmdletThings to Know about Examples in Cmdlet Help

  • Enumera todos los nombres de parámetro del comando, incluso cuando los nombres de parámetro son opcionales.List all of the parameter names in the command, even when the parameter names are optional. Esto ayuda al usuario a interpretar el comando fácilmente.This helps the user to interpret the command easily.

  • Evite los alias y los nombres de parámetros parciales, aunque funcionen en PowerShell.Avoid aliases and partial parameter names, even though they work in PowerShell.

  • En la descripción del ejemplo, explique el razonamiento de la construcción del comando.In the example description, explain the rational for the construction of the command. Explique por qué se eligen determinados parámetros y valores, y cómo se usan las variables.Explain why you chose particular parameters and values, and how you use variables.

  • Si el comando usa expresiones, explíqueles en detalle.If the command uses expressions, explain them in detail.

  • Si el comando usa las propiedades y los métodos de los objetos, especialmente las propiedades que no aparecen en la pantalla predeterminada, use el ejemplo como una oportunidad para informar al usuario sobre el objeto.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.

Vistas de ayuda que muestran ejemplosHelp Views that Display Examples

Los ejemplos solo aparecen en las vistas detalladas y completas de la ayuda de los cmdlets.Examples appear only in the Detailed and Full views of cmdlet Help.

Agregar un nodo examplesAdding an Examples Node

El siguiente XML muestra cómo agregar un nodo examples que contiene un solo nodo de ejemplo .The following XML shows how to add an Examples node that contains a single Example node. Agregue nodos de ejemplo adicionales para cada uno de los ejemplos que desee incluir en el tema.Add additional example nodes for each examples you want to include in the topic.

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

Agregar un título de ejemploAdding an Example Title

En el código XML siguiente se muestra cómo agregar un título para el ejemplo.The following XML shows how to add a title for the example. El título se usa para establecer el ejemplo, además de otros ejemplos.The title is used to set the example apart from other examples. PowerShell usa un encabezado estándar que incluye un número de ejemplo secuencial.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>

Agregar caracteres anterioresAdding Preceding Characters

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).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 el símbolo del sistema de 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>

Agregar el comandoAdding the Command

El siguiente XML muestra cómo agregar el comando real del ejemplo.The following XML shows how to add the actual command of the example. Al agregar el comando, escriba el nombre completo (no usar alias) de los cmdlets y parámetros.When adding the command, type the entire name (do not use alias) of cmdlets and parameters. Además, use caracteres en minúsculas siempre que sea posible.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>

Agregar una descripciónAdding a Description

El siguiente XML muestra cómo agregar una descripción para el ejemplo.The following XML shows how to add a description for the example. PowerShell usa un único conjunto de <maml:para> etiquetas para la descripción, aunque <maml:para> se pueden usar varias etiquetas.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>

Agregar salida de ejemploAdding Example Output

En el código XML siguiente se muestra cómo agregar el resultado del comando.The following XML shows how to add the output of the command. La información de los resultados del comando es opcional, pero en algunos casos resulta útil mostrar el efecto de usar parámetros específicos.The command results information is optional, but in some cases it is helpful to demonstrate the effect of using specific parameters. PowerShell usa dos conjuntos de etiquetas en blanco <maml:para> para separar los resultados del comando del 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>