Escribir ayuda para módulos de PowerShell

Los módulos de PowerShell pueden incluir temas de Ayuda sobre el módulo y sobre los miembros del módulo, como cmdlets, proveedores, funciones y scripts. El Get-Help cmdlet muestra los temas de Ayuda del módulo en el mismo formato que muestra ayuda para otros elementos de PowerShell y los usuarios usan comandos estándar Get-Help para obtener los temas de Ayuda.

En este documento se explica el formato y la ubicación correcta de los temas de ayuda del módulo y se sugieren directrices para el contenido de la Ayuda del módulo.

Tipos de ayuda del módulo

Un módulo puede incluir los siguientes tipos de Ayuda.

• Ayuda basada en XML

  • Ayuda del cmdlet. Los temas de Ayuda que describen los cmdlets de un módulo son archivos XML que usan el esquema de ayuda de comandos.
  • Ayuda del proveedor. Los temas de Ayuda que describen los proveedores de un módulo son archivos XML que usan el esquema de ayuda del proveedor.
  • Ayuda de la función. Los temas de Ayuda que describen funciones de un módulo pueden ser archivos XML que usan el esquema de ayuda de comandos o los temas de Ayuda basados en comentarios dentro de la función, o el script o el módulo de script.
  • Ayuda de script. Los temas de Ayuda que describen scripts de un módulo pueden ser archivos XML que usan el esquema de ayuda del comando o temas de Ayuda basados en comentarios en el script o el módulo de script.
  • La $PSHOME\Schemas\PSMaml carpeta contiene los archivos de esquema que definen el formato XML.

• Archivos de texto de ayuda conceptuales ("Acerca de")

  Puede usar un tema de ayuda conceptual ("acerca de") para describir el módulo y sus miembros y explicar cómo se pueden usar juntos los miembros para realizar tareas. De forma predeterminada, PowerShell incluye más de 100 de estos temas conceptuales acerca de la Ayuda. El nombre de archivo debe usar el about_<name>.help.txt formato , como about_MyModule.help.txt.

  Nota:

  El TOPIC encabezado de sección debe iniciarse en la primera columna de la primera línea del archivo. El contenido de la sección de la segunda línea debe coincidir con el nombre de archivo, sin el .help.txt sufijo. Debe sangr el contenido exactamente 4 espacios. La tercera línea debe estar en blanco. El SYNOPSIS encabezado de sección debe iniciarse en la primera columna de la cuarta línea. Debe sangr el contenido en la quinta línea exactamente 4 espacios. Estos requisitos son necesarios para que el Get-Help cmdlet reconozca el contenido correctamente.

  TOPIC
      about_<subject or module name>
  
  SYNOPSIS
      A short, one-line description of the topic contents.
  

  Puede usar la siguiente plantilla de ejemplo como punto de partida para escribir temas conceptuales de Ayuda. Excepto en las dos primeras secciones, la estructura de los temas de Ayuda conceptual es arbitraria. Los títulos de la sección restantes pueden ser los adecuados para el contenido.

  TOPIC
      about_<subject or module name>
  
  SYNOPSIS
      A short, one-line description of the topic contents.
  
  LONG DESCRIPTION
  
  A detailed, full description of the subject or purpose of the module.
  
  EXAMPLES
  
  Examples of how to use the module or how the subject feature works in
  practice.
  
  TROUBLESHOOTING
  
  Instructions for resolving common problems.
  
  SEE ALSO
  
  Text-only references for further reading. Hyperlinks can't work in the
  PowerShell console.
  

  Puede usar cualquier estilo y marcado que desee, pero PowerShell lo ve como texto sin formato y no hay ninguna representación especial del texto en la consola de PowerShell. Las siguientes sugerencias garantizan los mejores resultados de visualización y legibilidad.

  • Use UTF-8 con codificación BOM para asegurarse de que los caracteres especiales (multi byte) se muestran correctamente.
  • Subraya los encabezados de sección o usa todas las letras mayúsculas para que destaquen. Esto facilita el examen del contenido.
  • Limite la longitud de cada línea a 80 caracteres.
  • Sangría de bloques de código y salida de ejemplo para separarlos del prose circundante.

Selección de ubicación de la Ayuda del módulo

El Get-Help cmdlet busca los archivos de temas de ayuda del módulo en subdirectorios específicos del lenguaje del directorio del módulo.

Por ejemplo, el siguiente diagrama de estructura de directorio muestra la ubicación de los temas de Ayuda del módulo SampleModule.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Nota:

En el ejemplo, el <ModulePath> marcador de posición representa una de las rutas de acceso de la PSModulePath variable de entorno, como $HOME\Documents\Modules, $PSHOME\Moduleso una ruta de acceso personalizada que el usuario especifica.

Obtener ayuda del módulo

Cuando un usuario importa un módulo en una sesión, los temas de Ayuda de ese módulo se importan en la sesión junto con el módulo. Puede enumerar los archivos de temas de Ayuda en el valor de la clave FileList en el manifiesto del módulo, pero los temas de ayuda no se ven afectados por el Export-ModuleMember cmdlet .

Puede proporcionar temas de ayuda de módulos en diferentes idiomas. El Get-Help cmdlet muestra automáticamente los temas de ayuda del módulo en el idioma especificado para el usuario actual en el elemento Opciones regionales y de idioma del Panel de control. En Windows Vista y versiones posteriores de Windows, Get-Help busca los temas de Ayuda en subdirectorios específicos del lenguaje del directorio del módulo de acuerdo con los estándares de reserva de idioma establecidos para Windows.

A partir de PowerShell 3.0, la ejecución de un Get-Help comando para un cmdlet o función desencadena la importación automática del módulo. El Get-Help cmdlet muestra inmediatamente el contenido de los temas de ayuda en el módulo.

Si el módulo no contiene temas de ayuda y no hay temas de ayuda para los comandos del módulo en el equipo del usuario, Get-Help muestra la ayuda generada automáticamente. La ayuda generada automáticamente incluye la sintaxis de comandos, los parámetros y los tipos de entrada y salida, pero no incluye ninguna descripción. La ayuda generada automáticamente incluye texto que dirige al usuario a intentar usar el Update-Help cmdlet para descargar ayuda para el comando desde Internet o un recurso compartido de archivos. También recomienda usar el parámetro Online del Get-Help cmdlet para obtener la versión en línea del tema de ayuda.

Compatibilidad con ayuda actualizable

Los usuarios de PowerShell 3.0 y versiones posteriores de PowerShell pueden descargar e instalar archivos de ayuda actualizados para un módulo desde Internet o desde un recurso compartido de archivos local. Los Update-Help cmdlets y Save-Help ocultan los detalles de administración del usuario. Los usuarios ejecutan el Update-Help cmdlet y, a continuación, usan el Get-Help cmdlet para leer los archivos de ayuda más recientes del módulo en el símbolo del sistema de PowerShell. Los usuarios no necesitan reiniciar Windows ni PowerShell.

Los usuarios detrás de firewalls y aquellos sin acceso a Internet también pueden usar la Ayuda actualizable. Los administradores con acceso a Internet usan el Save-Help cmdlet para descargar e instalar los archivos de ayuda más recientes en un recurso compartido de archivos. A continuación, los usuarios usan el parámetro Path del Update-Help cmdlet para obtener los archivos de ayuda más recientes del recurso compartido de archivos.

Los autores de módulos pueden incluir archivos de ayuda en el módulo y usar la Ayuda actualizable para actualizar los archivos de ayuda o omitir los archivos de ayuda del módulo y usar la Ayuda actualizable tanto para instalarlos como para actualizarlos.

Para obtener más información sobre la Ayuda actualizable, vea Compatibilidad con ayuda actualizable.

Compatibilidad con la Ayuda en línea

Los usuarios que no pueden o no instalan archivos de ayuda actualizados en sus equipos suelen depender de la versión en línea de los temas de ayuda del módulo. El parámetro Online del Get-Help cmdlet abre la versión en línea de un tema de ayuda de cmdlets o funciones avanzadas para el usuario en su explorador de Internet predeterminado.

El Get-Help cmdlet usa el valor de la propiedad HelpUri del cmdlet o la función para buscar la versión en línea del tema de ayuda.

A partir de PowerShell 3.0, puede ayudar a los usuarios a encontrar la versión en línea de los temas de ayuda de funciones y cmdlets definiendo el atributo HelpUri en la clase de cmdlet o la propiedad HelpUri del atributo CmdletBinding . El valor del atributo es el valor de la propiedad HelpUri del cmdlet o la función.

Para obtener más información, consulte Compatibilidad con la Ayuda en línea.

Véase también

• Escritura de un módulo de PowerShell
• Compatibilidad con ayuda actualizable
• Compatibilidad con la Ayuda en línea