Cómo documentar nuestros scripts de PowerShell

A la hora de documentar nuestros scripts o nuestras funciones de PowerShell es necesario que conozcamos la estructura esperada para que el comando Get-Help o el propio Host pueda extraer la información.

La estructura es bastante sencilla, se basa en una palabra clave de ayuda, SYNOPSIS, DESCRIPTION o EXAMPLE, precedida de un punto. Tras ello, un comentario asociado a dicha palabra clave que empezará en la siguiente línea. Dicha estructura debe de ir dentro de un comentario de bloque o precedida por el símbolo # en cada línea. A continuación se muestra cómo sería en ambos casos

# .[palabra clave de ayuda]
# [contenido de la ayuda relacionado con la palabra clave]
 
<#
 .[palabra clave de ayuda]
 [contenido de la ayuda relacionado con la palabra clave]
#>

El bloque de documentación puede aparecer al principio del cuerpo de la función, al final de la función o anteriormente a la palabra clave reservada function. En el caso de los scripts, ésta puede situarse al principio del fichero precedida únicamente por otros comentarios o líneas en blanco o al final del mismo salvo si es un script firmado. Un detalle importante, si el primer miembro del script es una función será necesario dejar dos líneas en blanco para evitar que sea interpretada como la documentación de la función.

Documentación autogenerada por PowerShell

Por defecto, existe un conjunto de datos que por defecto PowerShell muestra y genera de forma automática cuando llamamos al comando Get-Help. Lo más importantes son los siguientes:

  • Name : Obtenido a partir del nombre del fichero de nuestro script o del nombre de la función.
  • Syntax : Extraído de la firma de nuestro script o función.
  • Parameter List : En esta ocasión, si incluímos detalles sobre los parámetros con lo que explicaremos a continuación, la información se extraerá de ahí. Si no, a partir de la firma de nuestro script o función.

Palabras clave que podemos utilizar

Junto con lo anterior, tenemos una colección de otros parámetros que podemos añadir a nuestra documentación para hacerla más completa.

  • SYNOPSIS : una pequea descripción de la función o el script. Esta palabra sólo se puede incluir una vez.
  • DESCRIPTION : Una extensión del parámetro anterior para describir de forma detallada qué realiza la función o el script. Esta palabra sólo se puede incluir una vez.
  • PARAMETER : La descripción de cada uno de los parámetros que nuestra función o script. Es necesario incluir esta palabra clave por cada parámetro que utilicemos. El orden que utilicemos para ponerlos será el orden en el que aparezcan en la ayuda de PowerShell.
  • EXAMPLE : Diferentes ejemmplos para para ayudar al usuario a utilizar nuestra función o script. Podemos añadir tantos ejemplos como deseemos./li>
  • INPUTS : Si vamos a usar este comando en una tubería, con esta palabra clave definiremos el tipo de objeto del .Net Framework que acepta en su entrada.
  • OUTPUTS : Similar al caso anterior pero sobre el tipo de objeto de .Net Framework que devolverá al finalizar su ejecucción.
  • NOTES : Información adicional que queramos añadir sobre nuestro script o función.

No son los únicos pero sí los que probablemente utilicemos más a menudo. Si tenemos curiosidad sobre qué otros parámetros podemos utilizar podemos consultar el artículo de la documentación asociado a este tema. Para ello, desde una consola lanzaremos lo siguiente:

Get-Help about_Comment_Based_Help

O directamente en la referencia de TechNet de forma online.

Un ejemplo de ello lo podéis ver en el script que publiqué para aprovisionar nuestras imágenes de Windows Nano Server.

Utilizando los nuevos perfiles de Azure para PowerShell

Hace unos pocos días se actualizaron las herramientas de PowerShell para Azure a su última versión, la 0.8.15. Entre las novedades se encuentra una que me acaba de resultar muy útil para gestionar múltiples suscripciones de Azure desde PowerShell: los perfiles.

Nota: Si quieres actualizar tu versión de las herramientas de PowerShell o instalarlas desde cero recuerda que te resultará más fácil utilizando el script de PowerShell que creé.

Si alguna vez has intentado ejecutar un script contra múltiples suscripciones seguro que te has encontrado con las dificultades de desplegar los recursos en la suscripción correcta. Un perfil es un contenedor para agrupar una serie de suscripciones para ser usado como forma de autentificación contra los extremos de Azure. Es posible seleccionar qué perfil queremos ejecutar en cada momento de forma general para la sesión actual de PowerShell o pasándolo a cada comando con el parámetro -Profile

Podemos crear un nuevo perfil en memoria con el comando New-AzureProfile. Soporta como métodos de autenticación Azure Active Directory o Certificados. En mi caso, la segunda opción era la que buscaba. Si queréis más detalles de cómo hacerlo con Active Directory podéis consultar la documentación con Get-Help New-AzureProfile

$profile = New-AzureProfile -SubscriptionId "GUIDIdentificadorSuscripcion" -Certificate "HuellaDelCertificado"

Dicho certificado lo habremos creado previamente siguiendo las instrucciones disponibles en la documentación y lo habremos subido a través del portal de Azure. La huella del certificado lo podremos obtener de forma fácil a través de Powershell

Get-Item "Cert:\CurrentUser\My\$HuellaDelCertificado"

Una vez que tengamos nuestro perfil creado, podremos seleccionarlo para utilizarlo en nuestra sesión actual con:

Select-AzureProfile -Profile $profile

Si queremos terminar con nuestro perfil en memoria y queremos volver a emplear el que está guardado en disco podemos hacerlo con:

Select-AzureProfile -Default

En el caso de que queramos ejecutar un comando en un perfil específico podemos utilizar el parámetro -Profile para evitar tener que cambiar con Select-AzureProfile al perfil que queremos y volver después a cambiar al perfil que estábamos usando anteriormente para continuar. Por ejemplo, creando una cuenta de almacenamiento en el perfil que tengo guardado en mi variable $produccion

New-AzureStorageAccount -StorageAccountName "myAzureStorageAccount" -Location "North Europe" -Type Standard_RAGRS -Profile $produccion

Espero que os salve de algún apuro ;)

Actualización del script para mantener tu módulo de PowerShell de Azure al día

Configurando un nuevo equipo me he dado cuenta de que el script que publiqué para mantener las herramientas de PowerShell para Azure al día tenía un fallo, si no tenías ya el módulo instalado no funcionaba. Así que nada, unos pequeños cambios y ahora también es posible instalarlas por primera vez con él. Para que sea más fácil está publicado en GitHub el código.

Cómo escribir nuestros scripts de PowerShell desde Visual Studio

A la hora de escribir nuestros scripts de PowerShell el ISE es generalmente nuestro editor preferido. También hay aquellos más castizos que con el bloc de notas tienen todo lo necesario pero un editor como ISE nos permite obtener extras como el autocompletado o la depuración haciéndonos más productivos. Lo mejor del ISE es que incluso permite ser extendido añadiendo funcionalidades nuevas como las que ofrece ISESteroids.

En este caso no quiero hablar sobre extensiones que se añaden al ISE para incorporar nuevas funcionalidades sino al revés, nuevos IDEs que añaden la capacidad de desarrollar scripts de PowerShell. En este caso estoy hablando de Visual Studio, uno de los entornos de desarrollo más conocidos por los desarrolladores, y en especial de las herramientas de PowerShell para Visual Studio. Si no has usado nunca Visual Studio, puedes descargar de forma gratuita la versión de comunidad .

¿Qué nos aportan las PowerShell Tools?

De forma nativa el soporte de Visual Studio para PowerShell es limitado, queda prácticamente reducido al resaltado de sintaxis. Sin embargo, esta extensión nos permite tener características extras en diferentes partes del editor como las siguientes.

  • El editor: gracias a la integración con IntelliSense es posible el autocompletado de código, tanto de cmdlets, funciones, variables o parámetros. Por otro lado, gracias al encapsulado de código es posible mostrar y ocultar los bloques de código o comentarios.
  • Editor de Visual Studio para PowerShell
    Editor de Visual Studio para PowerShell
  • El depurador: el objetivo de la extensión es mejorar el soporte a la depuración comparado con el ISE, para ello incorpora soporte para las ventanas de variables locales, puntos de ruptura y la pila de llamadas. Gracias a la ventana de variables locales es posible tener una vista global de lo que está sucediendo en este instante y los valores que tienen cada una de ellas; también permite expandir elementos complejos para ver sus propiedades como sucede con C# por ejemplo. Una de las diferencias respecto al ISE es la capacidad de modificar los valores desde este punto. Respecto a la ventana de puntos de ruptura, esta muestra la lista de puntos disponibles dentro del proyecto. A día de hoy no existe la opción de puntos condicionales. Finalmente, la ventana de la pila de llamadas permite ver de forma visual la situación actual de la pila gracias al comando Get-PSCallStack.
  • Depuración de PowerShell en Visual Studio
    Depuración de PowerShell en Visual Studio
  • Las pruebas unitarias: si queremos utilizar un enfoque de escritura de nuestro código basado en pruebas la extensión nos permite utilizar Pester para escribir nuestras pruebas unitarias y verificar que nuestras funciones se ejecutan de forma correcta.
  • Pester - Pruebas unitarias en PowerShell
    Pester – Pruebas unitarias en PowerShell

Si te ha convencido y lo quieres probar, la extensión es totalmente gratuita y se puede descargar desde la galería de extensiones de Visual Studio: PowerShell Tools for Visual Studio 2013

Obteniendo la última versión del módulo de PowerShell de Azure

Nota: El script ha sufrido modificaciones, te recomiendo consultar la última versión en su repositorio de GitHub :)

El ritmo de evolución que tienen las soluciones en la nube es abrumador, en cuanto te despistas por un momento nuevos productos y funcionalidades están disponibles. Esto es algo que a los que estamos acostumbrados a trabajar con Azure nos pasa, sólo hay que ver los últimos cambios en el portal de actualizaciones de los diferentes servicios.

Estas nuevas funcionalidades y servicios obligan a actualizar al mismo tiempo las herramientas de gestión. En mi caso, suelo trabajar con Azure a través de PowerShell. Si vosotros queréis trabajar con lo mismo, es posible instalar el módulo de dos formas diferentes: haciendo uso del Web Platform Installer o descargándote el instalador en un fichero .msi. Aunque el WebPI es muy útil para poner a punto tu equipo con todas las herramientas necesarias si trabajas con entornos web, yo prefiero gestionar directamente la instalación del módulo de PowerShell y no tener un programa intermedio que lo haga.

La forma manual de obtener la última versión es la siguiente:

  1. Acceder al portal de GitHub del equipo de Azure donde se encuentra el repositorio de las herramientas de PowerShell
  2. Localizar la opción de ver las últimas versiones públicas
  3. Seleccionar la instalación “Windows Standalone” y descargar el fichero
  4. Lanzar la instalación desde el fichero .msi

El proceso es siempre el mismo por lo que nos da juego a que lo automaticemos con un pequeño script de PowerShell para que lo haga por nosotros. Para obtener los datos necesarios haremos uso de la API que GitHub tiene disponible de forma pública. En particular, haremos uso de la opción de listar las versiones disponibles en un repositorio.

Vamos a ver cómo realizarlo de forma automática

En primer lugar necesitaremos saber cuál es la versión que tenemos disponible del módulo en nuestro PC; en el caso de que no haya ninguna finalizaremos el script ya que no tendremos versión con la que comparar para actualizarlo o no. Otra opción sería ofrecer directamente la descarga aunque no está implementado.

# Check the actual version of the Azure Powershell module if its available
$azureModule = Get-Module -ListAvailable | Where { $_.Name -eq "Azure"}
if ($azureModule -eq $null )
{
    Write-Output "Microsoft Azure PowerShell module is not available on your computer"
    Return
}
$azureInstalledVersion = $azureModule.Version

Tras conocer cuál es la versión que tenemos instalada el siguiente paso es conocer cuál es la última que está disponible en el repositorio de GitHub. Realizaremos la consulta contra la API y en el caso de que esta no devuelva la información esperada finalizaremos la ejecución. Otra posible comprobación a añadir es que la llamada a la API se establece correctamente.

# Check the latest version of the Azure Powershell module released on GitHub
$gitHubData = Invoke-RestMethod -Method Get -Uri "https://api.github.com/repos/Azure/azure-powershell/releases" 
$latestRelease = $gitHubData | Select -First 1
 
if (![System.Version]::TryParse($latestRelease[0].name, [ref]$latestReleaseVersion) )
{
    Write-Error "Information about the latest version cannot be retrieved." -Category ConnectionError -CategoryReason "The connection to GitHub API has not been established properly and the information has not been retrieved"
    Return
}

Si ya estamos con la versión más reciente no necesitaremos continuar.

if ($azureInstalledVersion -ge $latestReleaseVersion)
{
    Write-Output "Your Microsoft Azure Powershell module version ($azureInstalledVersion) is greater or equal to the latest version ($latestReleaseVersion)."
    Return
}

Sin embargo, si tenemos una versión anterior ofreceremos la opción de actualizarse a la última descargando el fichero .msi disponible en la descripción de la release.

# Check if the user wants to update the module
Write-Output "Your Microsoft Azure Powershell module version ($azureInstalledVersion) is not the latest ($latestReleaseVersion)."
$updateModule = Read-Host "Do you want to update it? (Y/N)"
 
if ($updateModule -ne "Y")
{
    Return
}
Updating Azure PowerShell Module
Confirmación de actualización

Si aceptamos, automáticamente nos descargará el instalador y lo ejecutará por lo que nos encontraremos con la página de inicio del asistente para completar nuestra actualización:

$installerUrl = $latestRelease.body | Select-String -Pattern "\[Windows Standalone]\((http://.*)\)" | %{ ($_.Matches.Groups)[1].Value }
$savedFilePath = "$env:HOMEDRIVE$env:HOMEPATH\Downloads\azure-powershell.$($latestRelease.name).msi"
Invoke-WebRequest -Uri $installerUrl -OutFile $savedFilePath
 
Write-Output "Launching installer"
Invoke-Item $savedFilePath
Updating Azure PowerShell Module
Asistente de instalación del módulo de Azure

Si continuamos con el asistente tendremos actualizado finalmente nuestro módulo de Azure en el equipo.