Ayuda para escribir scripts y funciones de PowerShell

Los scripts y funciones de PowerShell deben estar completamente documentados siempre que se compartan con otras personas. El cmdlet Get-Help muestra los temas de ayuda de funciones y scripts en el mismo formato que muestra la ayuda para los cmdlets, y todos los parámetros Get-Help funcionan en la ayuda de funciones y scripts. temas.

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.

Este documento explica el formato y la ubicación correcta de los temas de ayuda y sugiere pautas para el contenido.

Tipos de script y ayuda de funciones

Ayuda basada en comentarios

El tema de ayuda que describe un script o función se puede implementar como un conjunto de comentarios dentro del script o función. Al escribir ayuda basada en comentarios para un script y para funciones en un script, preste especial atención a las reglas para colocar la ayuda basada en comentarios. La 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 de comandos basados en XML

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

Cuando la palabra clave de comentario ExternalHelp 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 < código>Ayuda externa palabra clave.

Ayuda en línea

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

No existe un método establecido para escribir temas conceptuales ("Acerca de") para scripts y funciones. Sin embargo, puede publicar temas conceptuales en Internet y enumerar los temas y sus URL en la sección Enlaces relacionados de un tema de ayuda de comandos.

Consideraciones de contenido para la ayuda de scripts y 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 del script o de los parámetros de la función. Incluya también uno o dos comandos de muestra en la sección de ejemplos, incluso si decide omitir las descripciones de los ejemplos.
En todas las descripciones, haga referencia al comando como un script o función. Esta información ayuda al usuario a comprender y gestionar el comando.
Por ejemplo, la siguiente descripción detallada indica que el comando Nuevo tema es un script. Esto recuerda a los usuarios que deben especificar la ruta y el nombre completo cuando lo ejecutan.
"El script 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 particularmente útil para los usuarios cuando la sesión incluye varios comandos con el mismo nombre, algunos de los cuales pueden estar ocultos por un comando con mayor prioridad.
La función Disable-PSRemoting deshabilita todas las configuraciones de sesión en la computadora local...
En un tema de ayuda del script, explique cómo utilizar el script en su totalidad. Si también está escribiendo temas de ayuda para funciones en el script, mencione las funciones en el tema de ayuda del script e incluya referencias a los temas de ayuda de funciones en la sección Enlaces relacionados del tema de ayuda del script. Por el contrario, cuando una función sea parte de un script, explique en el tema de ayuda de la función el papel que desempeña la función en el script y cómo podría usarse de forma independiente. Luego, enumere el tema de ayuda del script en la sección Enlaces 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 al archivo de script en el comando de ejemplo. Esto recuerda a los usuarios que deben especificar la ruta 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 existe solo en la sesión actual y, para usarla en otras sesiones, deben agregarla o agregarle un perfil de PowerShell.
Get-Help muestra el tema de ayuda para una secuencia de comandos o función solo cuando el archivo de secuencia de comandos y los archivos del tema de ayuda se guardan en las ubicaciones correctas. Por lo tanto, no resulta ú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 en el documento que utilice para distribuir el script o la función.

Ver también

Redacción de temas de ayuda basados en comentarios