Simulación y confirmación en scripts de administración: -WhatIf/-Confirm de PowerShell y un indicador --dry-run en shell

Objetivo

Dotar a un script de administración de un modo que muestre lo que haría y de una forma de que quien lo invoca exija una confirmación explícita antes de ejecutar cualquier acción que modifique el estado.

Requisitos previos

Funciones de PowerShell escritas como funciones avanzadas ([CmdletBinding()]); para scripts de shell no hace falta ninguna herramienta especial, solo una convención.

Pasos

1. En PowerShell, coloca [CmdletBinding(SupportsShouldProcess)] justo encima del bloque param() de la función. about_Functions_CmdletBindingAttribute documenta SupportsShouldProcess como la propiedad que añade automáticamente a la función los parámetros comunes -WhatIf y -Confirm; no tienes que implementar los conmutadores tú mismo.
2. Antes de cada línea que modifique el estado, llama a if ($PSCmdlet.ShouldProcess($target, $action)) { <do the change> }. about_Functions_Advanced_Methods documenta ShouldProcess como el método que comprueba -WhatIf/-Confirm y devuelve si la operación debe continuar; cuando se pasó -WhatIf, ShouldProcess imprime la línea "What if:" y devuelve $false sin que tengas que escribir esa lógica.
3. Todo cmdlet que tu función invoque y que admita -WhatIf debe recibirlo de forma explícita (Remove-Item @params -WhatIf:$WhatIfPreference), de modo que la simulación de tu función sea también una simulación de todo lo que llama. La preferencia solo se propaga automáticamente a los comandos de la misma cadena de ámbitos, y no de forma fiable hacia otros módulos.
4. Establece ConfirmImpact = 'High' en el atributo CmdletBinding para las acciones destructivas, de modo que aparezca una solicitud de confirmación aunque quien invoca no haya pasado -Confirm (el valor predeterminado de $ConfirmPreference es High). En una sesión iniciada con -NonInteractive, esa solicitud falla en lugar de quedarse esperando, por lo que los invocadores desatendidos deben pasar -Confirm:$false de forma deliberada.
5. En un script de shell, añade un indicador explícito --dry-run (o -n) que se procese al principio y se guarde en una variable, por ejemplo DRY_RUN=0. Envuelve cada comando que modifique el estado: run() { if [ "$DRY_RUN" = 1 ]; then echo "DRY-RUN: $*"; else "$@"; fi; }, y luego invoca cada comando que modifique algo a través de run rm -f "$path", etc., sin duplicar nunca la lógica que decide qué se ejecuta.
6. Imprime el plan de la simulación con el mismo formato con el que la ejecución real registraría su actividad, de modo que comparar la salida de una simulación con la de una ejecución real sea una comprobación significativa.
7. Para la confirmación sin un TTY completo (contextos no interactivos, dirigidos por agentes), haz que el comportamiento predeterminado exija un --yes/-Confirm:$false explícito en lugar de "continuar en silencio"; es decir, que se requiera un indicador para omitir la confirmación, no uno para solicitarla.

Resultado esperado

MyFunction -WhatIf y el --dry-run de un script de shell informan de todas las acciones que realizarían sin cambiar nada; al ejecutarlos sin esos indicadores se llevan a cabo las mismas acciones que describió la simulación, sin lógica duplicada entre ambas rutas.

Límites y base de verificación

ShouldProcess solo controla las rutas de código alrededor de las cuales lo colocas: una función puede tener SupportsShouldProcess declarado y aun así modificar el estado en una rama que nunca llama a ShouldProcess, así que revisa cada línea que modifique algo de forma individual. El envoltorio run() de shell no genera una salida fiel para los comandos cuyo efecto real depende de datos que solo se conocen al ejecutarlos (por ejemplo, una consulta que devuelve un número de filas); la salida de la simulación en esos casos es necesariamente aproximada. Las redirecciones las realiza el shell que llama antes de invocar run, por lo que run cmd > file sigue truncando file en modo de simulación; envuelve esos pasos en run sh -c '...' o en una función.