Cómo usar funciones de PowerShell

1. Diferencia entre funciones y cmdlets en PowerShell
2. Introducción a las funciones en PowerShell
3. Agregar parámetros a funciones en PowerShell
4. Crear un parámetro simple en una función en PowerShell

Cuando escribimos un script de PowerShell, tenemos muchas opciones. Por ejemplo, podríamos escribir mil líneas de código para tareas, todo en un solo bloque de código.

Sin embargo, eso sería complicado. Así que, en su lugar, deberíamos escribir funciones de PowerShell.

Las funciones de PowerShell aumentan drásticamente la usabilidad y legibilidad de nuestro código, facilitando mucho su uso. En este artículo, aprenderemos a escribir funciones, agregar y gestionar los parámetros de nuestras funciones, y configurar funciones para aceptar entrada de tuberías.

Diferencia entre funciones y cmdlets en PowerShell

El concepto de una función de PowerShell puede sonar familiar porque se parece a los cmdlets nativos de PowerShell. Comandos como Write-Host y Start-Service, por ejemplo, son muy similares a las funciones.

Sin embargo, los cmdlets son piezas de código nombradas que resuelven un solo problema y no son fácilmente personalizables. La diferencia entre un cmdlet y una función es cómo se hacen estas construcciones.

Podemos ver qué comandos son cmdlets y funciones usando el cmdlet Get-Command y su parámetro -CommandType.

Get-Command -CommandType Function

El comando anterior devuelve todas las funciones que actualmente están cargadas en nuestra sesión de PowerShell o dentro de los módulos disponibles para PowerShell.

Introducción a las funciones en PowerShell

Usamos la palabra clave function para definir una función, seguida de un nombre descriptivo definido por el usuario y un conjunto de llaves. Dentro de las llaves hay un bloque de script que queremos que PowerShell ejecute.

A continuación, podemos ver una función primaria y la ejecución de esa función. La función, llamada Install-Software, utiliza Write-Host para mostrar un mensaje de salida en la consola (principalmente para simular la instalación).

Una vez definida, podemos usar el nombre de esta función para ejecutar el código dentro de su bloque de script.

Código de ejemplo:

function Install-Software {
    Write-Host 'The software has been installed.'
}

Install-Software

Salida:

The software has been installed.

Mejor práctica de convención de nombres de funciones con sintaxis Verbo-Sustantivo en PowerShell

El nombre de una función es esencial. Podemos nombrar nuestras funciones como queramos, pero el nombre siempre debe describir lo que hace la función.

La mejor práctica de convención de nombres de funciones en PowerShell es la sintaxis Verbo-Sustantivo.

Siempre debemos comenzar el nombre de una función con un verbo seguido de un guion y un sustantivo. Usa el cmdlet Get-Verb para encontrar la lista de verbos aprobados.

Definir una función avanzada en PowerShell

El tutorial asume que copiamos y pegamos el código anterior directamente en la consola de PowerShell en esta sección. También podemos definir funciones en un script.

Estábamos trabajando con una función pequeña en la sección anterior, así que definirla en la consola no fue un gran problema. La mayoría de las veces, sin embargo, tendremos funciones mucho más grandes.

Así que será más fácil definir esas funciones en un script o un módulo y luego llamar a ese script o módulo para cargar la función en memoria.

Como podemos imaginar, volver a escribir una función más grande cada vez que queramos ajustar su funcionalidad podría ser confuso.

Agregar parámetros a funciones en PowerShell

Las funciones pueden tener cualquier número de parámetros. Cuando creamos nuestras funciones, tendremos la opción de incluir parámetros y decidir cómo funcionan esos parámetros.

Los parámetros pueden ser opcionales o obligatorios, y pueden forzarse a aceptar uno de una lista limitada de argumentos o aceptar cualquier cosa.

Por ejemplo, el software ficticio que instalamos a través de la función Install-Software podría tener muchas versiones posibles. Pero actualmente, la función Install-Software no ofrece al usuario ninguna forma de especificar qué versión desea instalar.

Si fuéramos los únicos que usamos la función, podríamos cambiar el código dentro de ella cada vez que quisiéramos una versión específica, pero eso consumiría mucho tiempo. Este método también sería propenso a errores potenciales, y queremos que otros puedan usar nuestro código.

Introducir parámetros en nuestra función le permite tener variabilidad. Al igual que las variables nos permitieron escribir scripts que podían manejar muchas versiones de la misma situación, los parámetros nos permitirán escribir una sola función que haga una cosa de muchas maneras.

En este caso, queremos que instale versiones del mismo software y lo haga en muchas computadoras.

Primero, agreguemos un parámetro a la función que permita a un usuario o a nosotros especificar la versión a instalar.

Crear un parámetro simple en una función en PowerShell

Definir un parámetro en una función requiere un bloque de parámetros. El bloque de parámetros contiene todos los parámetros para la función.

Define un bloque de parámetros con la palabra clave param seguida de paréntesis, como se muestra a continuación.

Código de ejemplo:

function Install-Software {
    [CmdletBinding()]
    param()

    Write-Host 'The software has been installed.'
}

En este punto, la funcionalidad real de nuestra función no ha cambiado en absoluto. Solo hemos instalado la plomería, preparando la función para un parámetro.

Una vez que hemos agregado el bloque param, podemos crear el parámetro colocándolo dentro de sus paréntesis, como se muestra a continuación.

Código de ejemplo:

function Install-Software {
    [CmdletBinding()]
    param(
        [Parameter()]
        [string] $Version
    )

    Write-Host "The software version $Version has been installed."

}

Dentro del bloque param anterior, primero definiríamos el bloque Parameter. Usar el bloque Parameter() convertirá el parámetro en un “parámetro avanzado”.

Un bloque param vacío como el de aquí no hace nada, pero es requerido; explicaremos cómo usarlo en la siguiente sección.

Centraremos nuestra atención en el tipo [string] delante del nombre del parámetro. Transmitimos los parámetros colocando el tipo del parámetro entre corchetes antes del nombre de la variable del parámetro.

PowerShell siempre asignará valores predeterminados a una cadena. Arriba, cualquier cosa pasada en la variable $Version siempre se tratará como una cadena.

También agregamos $Version en nuestra declaración Write-Host. Luego, cuando ejecutemos la función Install-Software con el parámetro Version y le pasemos un número de versión, deberíamos obtener un mensaje que así lo muestre.

Código de ejemplo:

Install-Software -Version 2

Salida:

The software version 2 has been installed.