Dry-run and confirmation in admin scripts: PowerShell -WhatIf/-Confirm and a shell --dry-run flag

Goal

Give an admin script a mode that shows what it would do, and a way for the caller to require an explicit confirmation, before any state-changing action runs.

Prerequisites

PowerShell functions written as advanced functions ([CmdletBinding()]); for shell scripts, no special tooling — just a convention.

Steps

1. In PowerShell, put [CmdletBinding(SupportsShouldProcess)] directly above a function's param() block. about_Functions_CmdletBindingAttribute documents SupportsShouldProcess as the property that adds the common -WhatIf and -Confirm parameters to the function automatically — you do not implement the switches yourself.
2. Before every state-changing line, call if ($PSCmdlet.ShouldProcess($target, $action)) { <do the change> }. about_Functions_Advanced_Methods documents ShouldProcess as the method that checks -WhatIf/-Confirm and returns whether the operation should proceed; when -WhatIf was passed, ShouldProcess prints the "What if:" line and returns $false without you writing that logic.
3. Any cmdlet your function calls that itself supports -WhatIf should receive it explicitly (Remove-Item @params -WhatIf:$WhatIfPreference) so a dry run of your function is also a dry run of everything it calls; the preference propagates automatically only to commands in the same scope chain, not reliably into other modules.
4. Set ConfirmImpact = 'High' in the CmdletBinding attribute for destructive actions so a confirmation prompt appears even when the caller did not pass -Confirm (the default $ConfirmPreference is High). In a session started with -NonInteractive, that prompt fails instead of waiting, so unattended callers must pass -Confirm:$false deliberately.
5. In a shell script, add an explicit --dry-run (or -n) flag parsed at the top into a variable, e.g. DRY_RUN=0. Wrap every state-changing command: run() { if [ "$DRY_RUN" = 1 ]; then echo "DRY-RUN: $*"; else "$@"; fi; }, then call every mutating command through run rm -f "$path" etc., never duplicating the logic that decides what to run.
6. Print the dry-run plan in the same shape the real run would log, so comparing a dry run's output to a real run's output is a meaningful check.
7. For confirmation without a full TTY (agent-driven, non-interactive contexts), make the default require an explicit --yes/-Confirm:$false rather than defaulting to "proceed silently"; require a flag to skip confirmation, not a flag to request it.

Expected result

MyFunction -WhatIf and a shell script's --dry-run both report every action they would take without changing anything; running without those flags performs the same actions the dry run described, with no logic duplicated between the two paths.

Limits and test basis

ShouldProcess only gates the code paths you put it around; a function can still have SupportsShouldProcess declared and mutate state in a branch that never calls ShouldProcess, so review each mutating line individually. The run() shell wrapper does not fabricate accurate output for commands whose real effect depends on data only discovered by actually running them (e.g. a query that returns a row count) — dry-run output for those is necessarily an approximation. Redirections are performed by the calling shell before run is invoked, so run cmd > file still truncates file in dry-run mode; wrap such steps in run sh -c '...' or a function.