Argumentos y parámetros de un script de PowerShell

Un script que recibe parámetros se convierte en una herramienta: en lugar de editarlo cada vez, le dices qué hacer al llamarlo. En PowerShell se declaran en un bloque param, y con unos atributos obtienes validación, ayuda y autocompletado sin escribir una sola línea más.

Este script, precio.ps1, calcula el precio final de un producto. Todo lo que recibe está declarado en su bloque param, con tipos, valores por omisión y validaciones:

<#
.SYNOPSIS
Calcula el precio final de un producto con IVA y un descuento opcional.
.EXAMPLE
.\precio.ps1 -Precio 1299 -Descuento 10
#>
[CmdletBinding()]
param(
    [Parameter(Mandatory, Position = 0)]
    [ValidateRange(0.01, 1000000)]
    [double]$Precio,

    [ValidateRange(0, 90)]
    [int]$Descuento = 0,

    [ValidateSet("General", "Frontera")]
    [string]$Zona = "General",

    [switch]$Detalle
)
$tasa = if ($Zona -eq "Frontera") { 0.08 } else { 0.16 }
$conDescuento = $Precio * (1 - $Descuento / 100)
$total = $conDescuento * (1 + $tasa)
if ($Detalle) {
    "Precio:     {0,12:N2}" -f $Precio
    "Descuento:  {0,12:N2}" -f ($Precio - $conDescuento)
    "IVA {1,3:P0}:   {0,12:N2}" -f ($total - $conDescuento), $tasa
}
"Total:      {0,12:N2}" -f $total

Llamarlo de varias formas

consolaPS> ./precio.ps1 -Precio 1299
Total:          1,506.84
PS> ./precio.ps1 1299 -Descuento 10 -Detalle
Precio:         1,299.00
Descuento:        129.90
IVA 16%:         187.06
Total:          1,356.16
PS> ./precio.ps1 -Precio 1299 -Zona Frontera -Detalle
Precio:         1,299.00
Descuento:          0.00
IVA  8%:         103.92
Total:          1,402.92

Como $Precio tiene Position = 0, se puede pasar sin nombre. -Detalle es un [switch]: basta con escribirlo. Y el IVA del 8 % para la zona fronteriza muestra un parámetro con valores fijos.

Lo que pasa con un valor no válido

consolaPS> ./precio.ps1 -Precio 1299 -Descuento 95
precio.ps1: Cannot validate argument on parameter 'Descuento'. The 95 argument is greater than the maximum allowed range of 90. Supply an argument that is less than or equal to 90 and then try the command again.
PS> ./precio.ps1 -Precio 1299 -Zona Norte
precio.ps1: Cannot validate argument on parameter 'Zona'. The argument "Norte" does not belong to the set "General,Frontera" specified by the ValidateSet attribute. Supply an argument that is in the set and then try the command again.

El script ni siquiera empezó: PowerShell rechazó el valor y dijo por qué, con el nombre del parámetro. Toda esa validación sale gratis de los atributos. En la consola, además, al pulsar Tab después de -Zona te ofrece «General» y «Frontera».

La ayuda

El comentario del principio es la ayuda del script. Get-Help la muestra junto con la sintaxis, que PowerShell arma solo a partir del bloque param:

consolaPS> Get-Help ./precio.ps1

NAME
    /home/ana/proyecto/precio.ps1

SYNOPSIS
    Calcula el precio final de un producto con IVA y un descuento opcional.

SYNTAX
    /home/ana/proyecto/precio.ps1 [-Precio] <Double> [-Descuento <Int32>]
    [-Zona <String>] [-Detalle] [<CommonParameters>]

DESCRIPTION

RELATED LINKS

REMARKS
    To see the examples, type: "Get-Help /home/ana/proyecto/precio.ps1
    -Examples"
    For more information, type: "Get-Help /home/ana/proyecto/precio.ps1
    -Detailed"
    For technical information, type: "Get-Help /home/ana/proyecto/precio.ps1
    -Full"

Desde otra consola o desde un acceso directo

Para ejecutarlo desde el Símbolo del sistema, un archivo .bat o un acceso directo, se llama a pwsh con -File, y los parámetros van después de la ruta:

pwsh -NoProfile -File C:\Scripts\precio.ps1 -Precio 1299 -Detalle

-NoProfile evita cargar tu perfil, para que el script se comporte igual en cualquier computadora. Con Windows PowerShell 5.1 sería powershell.exe -NoProfile -ExecutionPolicy Bypass -File …; el -ExecutionPolicy Bypass solo afecta a esa ejecución.

Argumentos sin declarar: $args

"Recibí $($args.Count) argumentos"
foreach ($a in $args) { "- $a" }
PS> .\args.ps1 uno 'dos tres' 4Recibí 3 argumentos
- uno
- dos tres
- 4

Si un script no tiene bloque param, lo que le pases llega en la lista automática $args. Sirve para algo rápido, pero no tiene validación, ni ayuda, ni nombres, así que para cualquier script que vayas a reutilizar, mejor param.

Todos los scripts de esta página se ejecutaron con PowerShell 7.6.10 (LTS) en un contenedor Linux limpio sin acceso a la red, con la configuración regional de México, y pasaron PSScriptAnalyzer 1.25 sin avisos antes de publicarla; las salidas están copiadas de esa ejecución. Por eso las rutas salen como /home/ana/proyecto; en Windows verás algo como C:\Users\ana.