Escribir ayuda para scripts y funciones de PowerShell

Los scripts y funciones de PowerShell deben documentarse completamente siempre que se compartan con otros usuarios. El cmdlet Get-Help muestra los temas de ayuda de scripts y funciones en el mismo formato que muestra ayuda para cmdlets y todos los parámetros de Get-Help funcionan en temas de ayuda de scripts y funciones.

Los scripts de PowerShell pueden incluir un tema de ayuda sobre el script y temas de ayuda sobre cada función del script. Las funciones que se comparten independientemente de los scripts pueden incluir sus propios temas de ayuda.

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

Tipos de script y ayuda de funciones

Ayuda basada en comentarios

El tema de ayuda que describe un script o una función se puede implementar como un conjunto de comentarios dentro del script o la función. Al escribir ayuda basada en comentarios para un script y para funciones en un script, preste atención a las reglas para colocar la ayuda basada en comentarios. La selección de ubicación determina si el cmdlet Get-Help asocia el tema de ayuda con el script o una función. Para obtener más información sobre cómo escribir temas de ayuda basados en comentarios, consulte about_Comment_Based_Help.

Ayuda del comando XML-Based

El tema de ayuda que describe un script o una función se puede implementar en un archivo XML que usa el esquema de ayuda del comando. Para asociar el script o la función con el archivo XML, use la palabra clave de comentario .EXTERNALHELP seguida de la ruta de acceso y el nombre del archivo XML.

Cuando la palabra clave de .EXTERNALHELP comentario está presente, tiene prioridad sobre la ayuda basada en comentarios, incluso cuando Get-Help no puede encontrar un archivo de ayuda que coincida con el valor de la palabra clave .EXTERNALHELP.

Ayuda en pantalla

Puede publicar sus temas de ayuda en Internet y, a continuación, dirigir Get-Help para abrir los temas. Para obtener más información sobre cómo escribir temas de ayuda basados en comentarios, consulte Ayuda en línea auxiliar.

No hay ningún método establecido para escribir temas conceptuales ("Acerca de") para scripts y funciones. Sin embargo, puede publicar temas conceptuales en la lista de temas de Internet y sus direcciones URL en la sección Vínculos relacionados de un tema de ayuda de comandos.

Consideraciones de contenido para script y ayuda de funciones

• Si está escribiendo un tema de ayuda muy breve con solo algunas de las secciones de ayuda de comandos disponibles, asegúrese de incluir descripciones claras de los parámetros de script o función. Incluya también uno o dos comandos de ejemplo en la sección de ejemplos, incluso si decide omitir descripciones de ejemplo.

• En todas las descripciones, consulte el comando como script o función. Esta información ayuda al usuario a comprender y administrar el comando.

  Por ejemplo, la siguiente descripción detallada indica que el comando New-Topic es un script. Esto recuerda a los usuarios que necesitan especificar la ruta de acceso y el nombre completo al ejecutarla.

  "El script de New-Topic crea un tema conceptual en blanco para cada nombre de tema en el archivo de entrada..."

  La siguiente descripción detallada indica que Disable-PSRemoting es una función. Esta información es especialmente útil para los usuarios cuando la sesión incluye varios comandos con el mismo nombre, algunos de los cuales podrían estar ocultos por un comando con mayor prioridad.

  La función Disable-PSRemoting deshabilita todas las configuraciones de sesión en el equipo local...

• En un tema de ayuda de script, explique cómo usar el script en su conjunto. Si también está escribiendo temas de ayuda para funciones en el script, mencione las funciones del tema de ayuda del script e incluya referencias a los temas de ayuda de la función en la sección Vínculos relacionados del tema de ayuda del script. Por el contrario, cuando una función forma parte de un script, explique en el tema de ayuda de la función el rol que desempeña la función en el script y cómo se puede usar de forma independiente. A continuación, enumere el tema de ayuda del script en la sección Vínculos relacionados del tema de ayuda de la función.

• Al escribir ejemplos para un tema de ayuda de script, asegúrese de incluir la ruta de acceso al archivo de script en el comando de ejemplo. Esto recuerda a los usuarios que deben especificar la ruta de acceso explícitamente, incluso cuando el script está en el directorio actual.

• En un tema de ayuda de función, recuerde a los usuarios que la función solo existe en la sesión actual y, para usarla en otras sesiones, deben agregarla o agregarla a un perfil de PowerShell.

• Get-Help muestra el tema de ayuda de un script o función solo cuando el archivo de script y los archivos de temas de ayuda se guardan en las ubicaciones correctas. Por lo tanto, no es útil incluir instrucciones para instalar PowerShell o guardar o instalar el script o la función en un tema de ayuda de script o función. En su lugar, incluya las instrucciones de instalación del documento que use para distribuir el script o la función.

Véase también

Temas de Ayuda para la Escritura Comment-Based