Funciones

1. Estructura de una función

En PowerShell, como en muchos lenguajes, una función es un conjunto de instrucciones a las que damos un nombre. El principal interés de las funciones es que podemos llamarlas varias veces, sin tener que volver a escribir las instrucciones en cada llamada. Una función está constituida de los siguientes elementos:

un nombre;
un tipo de ámbito (opcional);
un bloque param (opcional);
un bloque de instrucciones.

En lo que se refiere al ámbito, abordaremos esta noción un poco más adelante en este capítulo. La escritura de una función necesita la sintaxis siguiente:

Function [<ámbito> :] <nombre de función> 
{ 
  param (<lista de parámetros>) 
  # bloque de instrucciones 
}

Tomemos por ejemplo la siguiente función:

Function Hola 
{ 
  $date = Get-Date 
  Write-Host "Hola, hoy es el $date" -Foreground Yellow 
}

Esta función es la más básica posible. En cada llamada, muestra un mensaje en amarillo en la consola. Para llamar a una función, basta simplemente con escribir su nombre:

PS > Hola 
Hola, hoy es el 13/01/2018 13:18:54

2. Uso de argumentos

Mencionamos los argumentos aquí para que el libro sea más completo, pero sepa que es mucho más conveniente usar parámetros (que se abordan en la siguiente sección). En efecto, los parámetros representan el medio para pasar valores a los scripts o funciones, desde la versión 2 de PowerShell.

Una noción interesante en el uso de funciones o de scripts es el paso de valores. Para ello, una técnica consiste en usar argumentos. Los argumentos son los valores situados detrás del nombre de la función cuando se la invoca. Aquí tiene la sintaxis de la llamada a una función con varios argumentos:

<Nombre de función> <Argumento1> <Argumento2> <ArgumentoN>

Por ejemplo

PS > Hola Pepe Paco

En este ejemplo, Pepe y Paco son los dos argumentos que se pasan a la función Hola.

Imaginemos que acabamos de crear una función que muestra un mensaje en un cuadro de diálogo. La pregunta es: ¿Cómo hacer para recuperar los argumentas de manera que los insertemos en un cuadro de diálogo? Pues la respuesta...

Scripts

Los scripts tienen un funcionamiento idéntico a las funciones en el sentido de que también pueden aprovechar el atributo [CmdletBinding] y todo lo que caracteriza a las funciones avanzadas, utilizar parámetros, proponer una ayuda integrada (como veremos a continuación), etc. La visión de Microsoft y en particular del equipo de PowerShell es permitir a los desarrolladores PowerShell realizar scripts que se comporten exactamente como comandos PowerShell nativos.

Por otra parte, los scripts PowerShell constituyen el entorno físico donde se almacenan generalmente las variables así como un conjunto de funciones. Tienen la extensión .ps1.

Sea cual sea la versión de PowerShell, también con la versión 5, todos los scripts tienen la extensión .ps1.

1. Estructuración de un script

Un script se estructura generalmente con las siguientes secciones:

# Nombre del script, autor, versión, etc. 
Declaración de parámetros 
... 
 
Declaración de funciones 
... 
 
Cuerpo principal del script 
...

Dicho esto, en su forma más minimalista, basta con que el script contenga el cuerpo principal, siendo el resto opcional. Generalmente encontraremos en las primeras líneas del script algunos comentarios describiendo brevemente:

El nombre del script,
Un número de versión,
La fecha de creación,
El nombre del autor.

Buena práctica: si desea aportar información adicional más precisa acerca del funcionamiento del script, por ejemplo sobre el uso de los parámetros, así como eventualmente proporcionar algún ejemplo de uso, le recomendamos facilitar una ayuda estructurada como se define en la sección de ayuda integrada a los scripts y funciones. Así la ayuda estará disponible para todos sus usuarios utilizando la línea de comandos siguiente: help MiScript.ps1. Todo script que se precie, un entorno empresarial, debería proporcionar una ayuda integrada.

2. Comentarios

Seguramente ya lo sepa, mediante los diferentes ejemplos que le hemos suministrado, los comentarios empiezan siempre por el carácter almohadilla «#». Un comentario puede estar situado en cualquier sitio en un script.

Por ejemplo:

# MiScript.ps1 
 
# Declaración de variables 
[int]$numArch = 0 # número...

DotSourcing

Llamamos «DotSourcing» al procedimiento que consiste en anteponer un punto y un espacio al nombre de un script (y su ruta completa o relativa, según el caso) o a un bloque de instrucciones. Esta técnica permite ejecutar el contenido de un script en el contexto actual. De esta forma, toda variable o función puede reutilizarse, a continuación, durante toda la vida del contexto. Tomemos como ejemplo el siguiente script que solo contiene funciones.

# funciones.ps1 
 
Function Invoke-WakeUp 
{ 
   Write-Host '¡Hola y buenos días!' -f Yellow 
}  
 
Function Get-CTempFiles 
{ 
   Get-ChildItem -Path C:\Temp  
}  
 
Function Get-CPUTime  
{  
   Get-Process | Where-Object {$_.CPU -gt 500} 
}

Al ejecutar este script de manera clásica, ninguna de las tres funciones no sería reutilizable, simplemente porque el contexto creado para la apertura del script se ha finalizado con él. Además este script no hace nada porque no realiza llamadas a las funciones declaradas en él.

PS > ./funciones.ps1 
PS > Invoke-WakeUp 
 
Despertador : The term 'Invoke-WakeUp' is not recognized as the name of 
a cmdlet, function, script file, or operable program. Check the spelling 
of the name...

Ayuda integrada a los scripts y funciones

Cuando desarrollamos funciones o scripts que deben utilizar otras personas, como por ejemplo en el marco del desarrollo de un módulo agrupando un conjunto de funciones, puede ser útil facilitar una ayuda.

En vez de escribir toneladas de documentación en forma de documentos Word asociados a nuestros módulos, scripts o funciones, PowerShell ofrece una funcionalidad extremadamente interesante: la posibilidad de incluir la ayuda directamente en el código, o fuera de él en un archivo XML (respetando la gramática de MAML).

La ventaja de suministrar la ayuda en nuestros scripts o funciones es que confiere un carácter profesional a nuestro trabajo, con un mínimo de esfuerzo. En efecto los scripts o funciones, disponiendo de ayuda, se comportan exactamente como los comandos nativos. Los usuarios dispondrán, por lo tanto, para cada una de sus realizaciones tres niveles de detalle, a saber: la ayuda estándar, detallada o completa.

Volvamos a utilizar la función Show-Popup estudiada anteriormente.

Function Show-Popup 
{ 
  param([string]$mensaje='Mensaje...', [string]$titulo='Título') 
 
  $WshShell = New-Object -ComObject wscript.Shell 
  $WshShell.Popup($mensaje, 0, $titulo) 
}

Para empezar, cargamos la función en nuestra sesión y pedimos la ayuda para ver qué...

Funciones y scripts