¡Consigue ayuda! Uso de la ayuda basada en comentarios en scripts de PowerShell

Seguramente ya utilizas comentarios dentro de tus scripts de PowerShell, y seguramente a ti también te han molestado los scripts no comentados.

Los comentarios en los scripts de PowerShell permiten documentar ciertos procesos directamente en el código. Además, se pueden agregar notas adicionales a los fragmentos de código, por ejemplo, si una función se va a ampliar con otras funciones.

Pero más allá de este contenido puramente informativo, los comentarios en PowerShell, usados correctamente, pueden usarse para artículos de ayuda sobre sus funciones. En este artículo, le mostraré cómo utilizar metadatos para obtener información del script a través de Get-Help.

Palabras clave de ayuda basadas en comentarios

La palabra mágica para nuestro proyecto es Ayuda basada en comentarios.

Como sugiere el nombre, este método nos permite generar información de ayuda a través de comentarios. . Estos comentarios deben estar organizados y formateados correctamente; descubrirá exactamente cómo en esta sección.

En principio, podemos distinguir entre dos tipos: Ayuda basada en comentarios para Funciones y para Scripts. El primero va un nivel más profundo y comienza con funciones que queremos proporcionar con metadatos. Sin embargo, si su código no está preparado en funciones, también es posible proporcionar un script completo con esta información.

Antes de ver su uso exacto, aquí enumero todas las palabras clave para la ayuda basada en comentarios:

KEYWORD

FUNCIÓN

SYNOPSIS

Breve descripción del script o función.

DESCRIPTION

Descripción detallada del código.

PARAMETER

Descripción de un parámetro utilizado. La palabra clave se utiliza varias veces (1 vez por parámetro). ¡El parámetro debe tener un nombre adicional después de la palabra clave!

INPUTS

Descripción de posibles objetos que se pueden pasar a la función a través de una canalización.

OUTPUTS

Valores de salida de la función.

NOTES

Información adicional sobre el código.

LINK

URL a la ayuda en línea correspondiente (si está disponible)

Para no ir más allá del alcance de este artículo, limitaré la lista a las palabras clave que se utilizan con más frecuencia. Puede encontrar más palabras clave en Microsoft Docs.

Nota: La información del encabezado del script también juega un papel importante para el uso de scripts en la plataforma de software ScriptRunner. Puede leer más al respecto aquí: Encabezados y parámetros de scripts de PowerShell para usar en ScriptRunner.

Uso de la ayuda basada en comentarios

Las palabras clave enumeradas anteriormente están anotadas en un formato específico en el código. Esto se parece a lo siguiente:

Notación de palabras clave de ayuda y contenido en el encabezado del script de PowerShell

Las palabras clave están encabezadas por un punto; el texto correspondiente se coloca debajo de la palabra clave. El bloque de palabras clave se comenta usando “<##>”.

Las secuencias de comandos y funciones basadas en comentarios difieren en el sentido de que el bloque de comentarios se coloca de manera diferente. Para funciones, es mejor colocar el bloque debajo del nombre de la función. Otras posibilidades son colocar el bloque directamente delante de la función (sin una línea en blanco) o al final del cuerpo de la función.

Si los scripts van a estar equipados con la información, el bloque Comentario se configura directamente al principio del código; lógicamente, esto también contiene información sobre el script en su conjunto y no sobre secciones parciales.

Ejemplo y uso de la ayuda basada en comentarios

A continuación, mostraremos cómo se puede utilizar en la práctica la ayuda basada en comentarios mediante una función que genera todos los objetos de directorio y archivo de un determinado directorio hasta una determinada profundidad de jerarquía.

PowerShell ya proporciona esta funcionalidad; el siguiente ejemplo sólo sirve para comprenderlo.

Función de ejemplo

El objetivo ahora es describir la funcionalidad mediante descripciones, ejemplos e información de parámetros en un artículo de ayuda.

Metadatos en el encabezado de la función

En este código se ha escrito un comentario de ayuda integral. En una llamada Get-Help sobre esta información, ahora obtenemos el siguiente resultado en la consola:

Salida de Get-Help Get-ChildItemDepth

El parámetro -Examples también se puede utilizar para generar todos los ejemplos disponibles:

Salida de los ejemplos almacenados en el script

Consejo: para obtener más ejemplos de scripts creados según las mejores prácticas de PowerShell, consulte nuestros ActionPacks de ScriptRunner.

Conclusión

En principio se puede decir que la ayuda basada en comentarios ofrece grandes beneficios para los departamentos de TI. No solo puede obtener una descripción general rápida de las funciones creadas usted mismo, sino que sus colegas no tienen que abrirse camino a través de numerosas líneas de código para adivinar la funcionalidad básica.

Debido a su longitud limitada, el nombre del script sólo puede dar una indicación aproximada de la función de un script sin poder entrar en información detallada. Esta forma de crear ayuda también ahorra la necesidad de documentación externa del código.

Si existe una política básica o un código de conducta que requiere explícitamente el uso de estas secciones de ayuda, recomiendo encarecidamente el módulo Pester. Se puede configurar para verificar el código para detectar la presencia de artículos de ayuda antes de cada lanzamiento. Incluso puedes comprobar si cada parámetro tiene una descripción.