Búsqueda de sitios web

Cómo agregar el nombre del cmdlet y la sinopsis 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.

Esta sección describe cómo agregar contenido que se muestra en las secciones NOMBRE y SYNOPSIS de la ayuda del cmdlet. En el archivo de Ayuda, este contenido se agrega al nodo Comando para cada cmdlet.

Nota

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

Para agregar el nombre del cmdlet y una sinopsis

  • La Ayuda del cmdlet puede mostrar dos descripciones del cmdlet. La primera descripción es una breve descripción que se conoce como sinopsis. La segunda descripción es una descripción más detallada que se analiza en Agregar la descripción detallada a un tema de ayuda de cmdlet. Ambas descripciones deben escribirse en un solo párrafo.

  • En la sinopsis no repita el nombre del cmdlet. Informar al usuario que el cmdlet Get-Server obtiene un servidor es breve, pero no informativo. En su lugar, utilice sinónimos y agregue detalles a la descripción.

    Ejemplo: "Obtiene un objeto que representa una computadora local o remota".

  • Utilice verbos simples como "obtener", "crear" y "cambiar" en la sinopsis. Evite el uso de "establecer" porque es vago y palabras sofisticadas como "modificar".

    Ejemplo: "Obtiene información sobre la firma Authenticode en un archivo".

  • Escribe con voz activa. Por ejemplo, "Usar el objeto TimeSpan..." es mucho más claro que "el objeto TimeSpan se puede utilizar para..."

  • Evite el verbo "mostrar" al describir cmdlets que obtienen objetos. Aunque Windows PowerShell muestra datos de cmdlet, es importante presentarles a los usuarios el concepto de que el cmdlet devuelve objetos de .NET Framework cuyos datos pueden no mostrarse. Si enfatiza la visualización, es posible que el usuario no se dé cuenta de que el cmdlet puede haber devuelto muchas otras propiedades y métodos útiles que no se muestran.

Ver también

SDK de Windows PowerShell

Artículos relacionados