Cómo agregar una descripción del cmdlet

Note

La creación manual de ayuda basada en XML es muy difícil. El módulo PlatyPS le permite escribir ayuda en Markdown y, a continuación, convertirlo a ayuda basada en XML. Esto facilita mucho la escritura y el mantenimiento de la ayuda. platyPS también puede crear los paquetes de ayuda actualizables automáticamente. Para obtener más información, consulte ayuda basada en XML mediante PlatyPS.

En esta sección se describe cómo agregar contenido que se muestra en la sección DESCRIPTION de la Ayuda del cmdlet. En el archivo de ayuda, este contenido se agrega al nodo Comando para cada cmdlet.

Note

Para obtener una vista completa de un archivo de Ayuda, abra uno de los dll-Help.xml archivos ubicados en el directorio de instalación de PowerShell. Por ejemplo, el Microsoft.PowerShell.Commands.Management.dll-Help.xml archivo contiene contenido para varios de los cmdlets de PowerShell.

Para agregar una descripción

El <maml:description> nodo contiene la descripción detallada del cmdlet. Este elemento contiene uno o varios <maml:para> elementos. La descripción se incluye en un <maml:para> elemento . En el ejemplo siguiente se muestra la estructura del XML:

<maml:description>
  <maml:para>...</maml:para>
</maml:description>

Sugerencias de escritura

  • Empiece por explicar las características básicas del cmdlet con más detalle. En muchos casos, puede explicar los términos usados en el nombre del cmdlet e ilustrar conceptos desconocidos con un ejemplo. Por ejemplo, si el cmdlet anexa datos a un archivo, explique que agrega datos al final de un archivo existente.

  • Para buscar todas las características del cmdlet, revise la lista de parámetros. Describir la función principal del cmdlet y, a continuación, incluir otras funciones y características. Por ejemplo, si la función principal del cmdlet es cambiar una propiedad, pero el cmdlet puede cambiar todas las propiedades, por ejemplo, en la descripción detallada. Si los parámetros del cmdlet permiten a los usuarios solicitar información de diferentes maneras, explíquela.

  • Incluya información sobre las formas en que los usuarios pueden usar el cmdlet, además de los usos obvios. Por ejemplo, puede usar el objeto que recupera el Get-Host cmdlet para cambiar el color del texto en la ventana de comandos de Windows PowerShell.

    Ejemplo: "El Get-Acl cmdlet obtiene objetos que representan el descriptor de seguridad de un archivo o recurso. El descriptor de seguridad contiene las listas de control de acceso (ACL) del recurso. La ACL especifica los permisos que los usuarios y los grupos de usuarios tienen para acceder al recurso".

  • La descripción detallada debe describir el cmdlet, pero no debe describir los conceptos que usa el cmdlet. Coloque definiciones de concepto en Notas adicionales.

Véase también

Windows SDK de PowerShell

  • Last updated on