Lección 5 de 8: funciones, parámetros y módulos en PowerShell. Cuando un script crece, se parte en funciones con nombre, que reciben datos, los validan y devuelven resultados. Aquí verás cómo escribirlas con param, cómo hacer parámetros obligatorios y validados, cómo darles -WhatIf y ayuda con Get-Help, y cómo juntarlas en un módulo para reutilizarlas.
Tu primera función
Una función es un bloque de código con nombre que puedes llamar las veces que quieras. Se declara con function, recibe sus datos en un bloque param( ) y devuelve todo lo que escribe: no hace falta return, aunque existe. Lo normal es llamarla con un verbo aprobado y un sustantivo, como los cmdlets.
function Get-Iva {
param(
[double]$Monto,
[double]$Tasa = 0.16
)
$Monto * $Tasa
}
Get-Iva -Monto 1000
Get-Iva -Monto 1000 -Tasa 0.08
Get-Iva 2500
$iva = Get-Iva -Monto 349.50
"IVA del mouse: {0:N2}" -f $ivasalida160 80 400 IVA del mouse: 55.92
Los parámetros se pasan como a los cmdlets, con su nombre y un guion. Si no das el nombre, se asignan por posición: Get-Iva 2500 puso 2500 en $Monto, el primero. $Tasa tiene un valor por omisión, así que se puede omitir.
El error que te ahorra: llamar a una función con paréntesis y comas
En casi todos los lenguajes una función se llama así: sumar(2, 3). En PowerShell eso hace otra cosa:
function Sumar {
param($A, $B)
"A = [$A], B = [$B]"
$A + $B
}
Sumar(2, 3)
"---"
Sumar 2 3salidaA = [2 3], B = [] 2 3 --- A = [2], B = [3] 5
Con Sumar(2, 3), los paréntesis y la coma crearon una lista de dos elementos que se pasó entera como primer parámetro; $B se quedó vacío. Y como la lista llega como $A, $A + $B devuelve la misma lista. Las funciones de PowerShell se llaman como los cmdlets: con espacios, Sumar 2 3, o mejor, con nombres, Sumar -A 2 -B 3. Los paréntesis con coma solo se usan para los métodos de .NET, como "hola".Substring(0, 2). (Desactivamos la regla de verbos aprobados porque «Sumar» no lo es: en un script real, Add-Numero.)
Todo lo que sale se devuelve
Una función devuelve todo lo que produce cualquier línea que no se guarde en una variable. Es cómodo, pero obliga a cuidar las líneas que escriben algo «de paso»:
function Get-NumeroPar {
param([int[]]$Numeros)
$lista = [System.Collections.ArrayList]::new()
foreach ($n in $Numeros) {
if ($n % 2 -eq 0) { $lista.Add($n) }
}
return $lista
}
$r = Get-NumeroPar -Numeros 1, 2, 3, 4, 6
"Recibí $($r.Count) valores: $r"salidaRecibí 6 valores: 0 1 2 2 4 6
Esperábamos tres pares y llegaron seis valores: ArrayList.Add() devuelve la posición donde guardó el elemento (0, 1, 2), y esas posiciones también salieron de la función. return $lista solo añade la lista al final de lo que ya había salido. La solución es tirar lo que no quieres con $null = $lista.Add($n) (o [void]), o mejor, usar una List genérica, cuyo Add() no devuelve nada:
function Get-NumeroPar {
param([int[]]$Numeros)
$lista = [System.Collections.Generic.List[int]]::new()
foreach ($n in $Numeros) {
if ($n % 2 -eq 0) { $lista.Add($n) }
}
$lista
}
$r = Get-NumeroPar -Numeros 1, 2, 3, 4, 6
"Recibí $($r.Count) valores: $r"salidaRecibí 3 valores: 2 4 6
Funciones avanzadas: parámetros obligatorios y validados
Con [CmdletBinding()] arriba del param, la función se comporta como un cmdlet: acepta -Verbose, -ErrorAction y los demás parámetros comunes. Cada parámetro puede llevar atributos que PowerShell comprueba antes de ejecutar el cuerpo:
function New-Pedido {
[CmdletBinding()]
param(
[Parameter(Mandatory)]
[string]$Cliente,
[ValidateRange(1, 100)]
[int]$Piezas = 1,
[ValidateSet("Normal", "Express")]
[string]$Envio = "Normal",
[switch]$Regalo
)
Write-Verbose "Creando pedido para $Cliente"
[pscustomobject]@{
Cliente = $Cliente
Piezas = $Piezas
Envio = $Envio
Regalo = $Regalo.IsPresent
}
}
New-Pedido -Cliente "Ana" -Piezas 3 -Envio Express -Regalo -Verbose
New-Pedido -Cliente "Luis" -Piezas 500salidaVERBOSE: Creando pedido para Ana
Cliente Piezas Envio Regalo
------- ------ ----- ------
Ana 3 Express True
New-Pedido: /home/ana/proyecto/validar.ps1:25
Line |
25 | New-Pedido -Cliente "Luis" -Piezas 500
| ~~~
| Cannot validate argument on parameter 'Piezas'. The 500 argument is
| greater than the maximum allowed range of 100. Supply an argument that
| is less than or equal to 100 and then try the command again.Lo que hace cada atributo:
[Parameter(Mandatory)]: el parámetro es obligatorio. Si no lo das en la consola, PowerShell te lo pregunta; en un script desatendido, falla.[ValidateRange(1, 100)]: solo acepta números en ese rango. Con 500, la función ni siquiera empezó: el error lo dio PowerShell, con el nombre del parámetro y el motivo.[ValidateSet(…)]: solo acepta esos valores, y además la consola los ofrece al pulsar Tab.[switch]: un interruptor sin valor. Si lo escribes (-Regalo), vale verdadero.Write-Verbose: un mensaje que solo se ve si llamas a la función con-Verbose. Ideal para explicar lo que hace sin ensuciar la salida normal.
Fíjate en que el error no detuvo el script: el pedido de Ana sí se creó y el script terminó con código 0. Un error de un cmdlet o de una función, por defecto, se muestra y la ejecución sigue. Cómo controlarlo es el tema de la lección 7.
-WhatIf y -Confirm en tus funciones
Si tu función cambia algo (borra, mueve, renombra), dale -WhatIf gratis con SupportsShouldProcess. Dentro, cada cambio se envuelve en if ($PSCmdlet.ShouldProcess(…)), y los cmdlets que llames heredan el modo de prueba:
function Remove-Temporal {
[CmdletBinding(SupportsShouldProcess)]
param([string]$Carpeta = ".")
foreach ($archivo in Get-ChildItem -Path $Carpeta -Filter *.tmp -File) {
if ($PSCmdlet.ShouldProcess($archivo.Name, "Borrar archivo temporal")) {
Remove-Item -LiteralPath $archivo.FullName
}
}
}
"a.tmp", "b.tmp", "nota.txt" | ForEach-Object { New-Item -Path $_ -ItemType File | Out-Null }
Remove-Temporal -WhatIf
"Después de -WhatIf: $((Get-ChildItem -Filter *.tmp).Count) temporales"
Remove-Temporal
"Después de ejecutarla: $((Get-ChildItem -Filter *.tmp).Count) temporales"salidaWhat if: Performing the operation "Borrar archivo temporal" on target "a.tmp". What if: Performing the operation "Borrar archivo temporal" on target "b.tmp". Después de -WhatIf: 2 temporales Después de ejecutarla: 0 temporales
Ayuda integrada
Un comentario con un formato especial, justo dentro de la función, se convierte en su ayuda, y Get-Help la muestra como la de cualquier cmdlet:
function ConvertTo-Peso {
<#
.SYNOPSIS
Convierte dólares a pesos mexicanos.
.PARAMETER Dolares
La cantidad en dólares.
.PARAMETER TipoDeCambio
Pesos por dólar.
.EXAMPLE
ConvertTo-Peso -Dolares 100 -TipoDeCambio 18.25
#>
param(
[Parameter(Mandatory)][double]$Dolares,
[Parameter(Mandatory)][double]$TipoDeCambio
)
$Dolares * $TipoDeCambio
}
Get-Help ConvertTo-Peso -ExamplessalidaNAME
ConvertTo-Peso
SYNOPSIS
Convierte dólares a pesos mexicanos.
-------------------------- EXAMPLE 1 --------------------------
PS > ConvertTo-Peso -Dolares 100 -TipoDeCambio 18.25Scripts con parámetros
Un script entero puede tener su bloque param, como primera instrucción del archivo, y se le pasan los parámetros igual que a una función. Guarda esto como saludar.ps1:
param(
[Parameter(Mandatory)]
[string]$Nombre,
[int]$Veces = 1
)
foreach ($i in 1..$Veces) {
"Hola, $Nombre ($i)"
}PS> .\saludar.ps1 -Nombre Marta -Veces 2Hola, Marta (1) Hola, Marta (2)
Así tus scripts se vuelven herramientas: en vez de editar una variable al principio cada vez, se la pasas al llamarlo. El ejemplo de argumentos de un script lo lleva más lejos.
Ámbito: lo de dentro se queda dentro
$contador = 10
function Add-Uno {
$contador = $contador + 1
"Dentro: $contador"
}
Add-Uno
"Fuera: $contador"salidaDentro: 11 Fuera: 10
Una función puede leer las variables del script, pero al asignarles algo crea una copia local: la de fuera no cambia. Es una protección. Si de verdad necesitas cambiar una variable del script, existe $script:contador, pero casi siempre es mejor que la función devuelva el valor nuevo y que quien la llama lo guarde.
Módulos: tus funciones en un solo lugar
Cuando tienes varias funciones útiles, se guardan en un módulo: un archivo con extensión .psm1. Export-ModuleMember decide cuáles quedan visibles para quien lo importe; las demás son internas. Este es Utilidades.psm1:
function Get-Iva {
param([double]$Monto, [double]$Tasa = 0.16)
Get-Redondeo ($Monto * $Tasa)
}
function Get-Redondeo {
param([double]$Valor)
[math]::Round($Valor, 2, [MidpointRounding]::AwayFromZero)
}
Export-ModuleMember -Function Get-IvaImport-Module ./Utilidades.psm1 Get-Iva -Monto 349.50 (Get-Module Utilidades).ExportedFunctions.Keys Get-Command Get-Redondeo -ErrorAction SilentlyContinue "Get-Redondeo es interna: no se ve desde fuera"
salida55.92 Get-Iva Get-Redondeo es interna: no se ve desde fuera
Si guardas el módulo en una carpeta con su mismo nombre (Utilidades\Utilidades.psm1) dentro de Documentos\PowerShell\Modules, PowerShell lo encuentra solo, sin Import-Module: basta con usar una de sus funciones. La lista de carpetas donde busca está en $env:PSModulePath. Y para instalar módulos de otros, la PowerShell Gallery: Install-PSResource NombreDelModulo, o en la 5.1, Install-Module NombreDelModulo -Scope CurrentUser.
Ojo con la seguridad: instala módulos solo de quien confías
Un módulo es código que se ejecuta con tus permisos. La PowerShell Gallery es pública: cualquiera puede publicar, y ha habido paquetes con nombres casi iguales a los de módulos populares. Antes de instalar, revisa el autor, las descargas y la página del proyecto con Find-PSResource NombreDelModulo, escribe el nombre exacto y, en una computadora del trabajo, pregunta si tu empresa tiene un repositorio aprobado.
Retos
Reto 1. Escribe una función Get-Promedio que reciba una lista de números (obligatoria) y devuelva el promedio con dos decimales.
Ver la solución
function Get-Promedio {
param([Parameter(Mandatory)][double[]]$Numeros)
$suma = 0
foreach ($n in $Numeros) { $suma += $n }
[math]::Round($suma / $Numeros.Count, 2)
}
Get-Promedio -Numeros 8.5, 9, 7.25, 10salida8.69
[double[]] declara una lista de números con decimales; los valores se pasan separados por comas.
Reto 2. Haz una función Test-Rfc que reciba un texto y diga si parece un RFC de persona física: cuatro letras, seis números de fecha y tres caracteres de homoclave. Usa [ValidateNotNullOrEmpty()] en el parámetro.
Ver la solución
function Test-Rfc {
param([ValidateNotNullOrEmpty()][string]$Rfc)
$Rfc -cmatch '^[A-ZÑ&]{4}\d{6}[A-Z0-9]{3}$'
}
Test-Rfc -Rfc "GODE561231GR8"
Test-Rfc -Rfc "gode561231gr8"
Test-Rfc -Rfc "GODE5612"salidaTrue False False
-cmatch distingue mayúsculas, como el RFC. Para validarlo de verdad, con el dígito verificador, está nuestra herramienta Validar RFC.
Reto 3. ¿Qué escribe esto? Piénsalo antes de mirar: una función Get-Doble que hace "Calculando..." en una línea y return $X * 2 en la siguiente, y después $r = Get-Doble -X 21 y $r.Count.
Ver la solución
function Get-Doble {
param([int]$X)
"Calculando..."
return $X * 2
}
$r = Get-Doble -X 21
$r.Count
$rsalida2 Calculando... 42
Escribe 2, porque la función devolvió dos cosas: el texto «Calculando…» y el 42. Para mostrar un mensaje sin que forme parte del resultado, usa Write-Verbose o Write-Information; Write-Host también escribe en pantalla sin devolver nada, aunque PSScriptAnalyzer lo desaconseja en funciones.
Todos los scripts de esta lección se ejecutaron con PowerShell 7.6.10 (la versión LTS) en un contenedor limpio sin acceso a la red, y se revisaron con PSScriptAnalyzer 1.25 antes de publicarla; las salidas están copiadas de esa ejecución. El contenedor es Linux, así que las rutas salen como /home/ana/proyecto; en tu Windows verás algo como C:\Users\ana. Mira tu versión con $PSVersionTable.PSVersion.
