Dry-run e confirmação em scripts de administração: -WhatIf/-Confirm no PowerShell e uma flag --dry-run no shell

Objetivo

Dar a um script de administração um modo que mostre o que ele faria e uma forma de o chamador exigir confirmação explícita, antes que qualquer ação que altere estado seja executada.

Pré-requisitos

Funções PowerShell escritas como funções avançadas ([CmdletBinding()]); para scripts de shell, nenhuma ferramenta especial, apenas uma convenção.

Passos

1. No PowerShell, coloque [CmdletBinding(SupportsShouldProcess)] logo acima do bloco param() da função. A documentação about_Functions_CmdletBindingAttribute descreve SupportsShouldProcess como a propriedade que adiciona automaticamente à função os parâmetros comuns -WhatIf e -Confirm; você não precisa implementar os switches.
2. Antes de cada linha que altera estado, chame if ($PSCmdlet.ShouldProcess($target, $action)) { <do the change> }. A documentação about_Functions_Advanced_Methods descreve ShouldProcess como o método que verifica -WhatIf/-Confirm e retorna se a operação deve prosseguir; quando -WhatIf foi passado, ShouldProcess imprime a linha "What if:" e retorna $false, sem que você escreva essa lógica.
3. Qualquer cmdlet chamado pela sua função que também suporte -WhatIf deve recebê-lo explicitamente (Remove-Item @params -WhatIf:$WhatIfPreference), para que um dry run da sua função seja também um dry run de tudo o que ela chama; a preferência só se propaga automaticamente para comandos na mesma cadeia de escopo, não de forma confiável para outros módulos.
4. Defina ConfirmImpact = 'High' no atributo CmdletBinding para ações destrutivas, de modo que um prompt de confirmação apareça mesmo quando o chamador não passou -Confirm (o valor padrão de $ConfirmPreference é High). Em uma sessão iniciada com -NonInteractive, esse prompt falha em vez de ficar esperando, então chamadores não supervisionados devem passar -Confirm:$false de forma deliberada.
5. Em um script de shell, adicione uma flag explícita --dry-run (ou -n), lida no início para uma variável, por exemplo DRY_RUN=0. Envolva cada comando que altera estado: run() { if [ "$DRY_RUN" = 1 ]; then echo "DRY-RUN: $*"; else "$@"; fi; }, e chame cada comando mutante através de run rm -f "$path" etc., sem nunca duplicar a lógica que decide o que executar.
6. Imprima o plano do dry run no mesmo formato que a execução real registraria no log, para que comparar a saída de um dry run com a de uma execução real seja uma verificação útil.
7. Para confirmação sem um TTY completo (contextos não interativos, conduzidos por agentes), faça com que o padrão exija um --yes/-Confirm:$false explícito em vez de "prosseguir em silêncio"; exija uma flag para pular a confirmação, não uma flag para solicitá-la.

Resultado esperado

MyFunction -WhatIf e o --dry-run de um script de shell informam todas as ações que executariam, sem alterar nada; executar sem essas flags realiza as mesmas ações que o dry run descreveu, sem lógica duplicada entre os dois caminhos.

Limites e base de verificação

ShouldProcess só protege os caminhos de código em torno dos quais você o coloca; uma função pode ter SupportsShouldProcess declarado e ainda assim alterar estado em um ramo que nunca chama ShouldProcess, por isso revise cada linha mutante individualmente. O wrapper run() do shell não consegue produzir uma saída fiel para comandos cujo efeito real depende de dados que só se descobrem ao executá-los de fato (por exemplo, uma consulta que retorna o número de linhas); a saída do dry run nesses casos é necessariamente uma aproximação. Os redirecionamentos são feitos pelo shell chamador antes de run ser invocado, então run cmd > file ainda trunca file no modo dry-run; envolva esses passos em run sh -c '...' ou em uma função.