For any advanced function that changes persistent state, add [CmdletBinding(SupportsShouldProcess)] and place $PSCmdlet.ShouldProcess() immediately before each mutation. That pattern gives callers working -WhatIf previews and -Confirm prompts without manually declaring either parameter.
The safe implementation pattern
Resolve targets, validate inputs and perform non-mutating preparation first. Guard the actual change, not the whole function, with ShouldProcess.
![[Windows PowerShell Pocket Reference: Portable Help for PowerShell Scripters (Pocket Reference (O'Reilly))] [By: Holmes, Lee] [December, 2012]](https://m.media-amazon.com/images/I/51H-gSSyDWL._SL160_.jpg)
function Set-ExampleThing {
[CmdletBinding(SupportsShouldProcess)]
param(
[Parameter(Mandatory)]
[string] $Name
)
# Validation and setup can still run with -WhatIf.
$target = "ExampleThing '$Name'"
if ($PSCmdlet.ShouldProcess($target, 'Update')) {
# Put the persistent change here.
}
}SupportsShouldProcess opts the function into PowerShell’s common -WhatIf and -Confirm parameters. It does not create a $WhatIf variable, so do not test a manually declared switch. Use the method supplied through $PSCmdlet.
Choose useful target and operation text
The two-argument form, ShouldProcess($target, $operation), produces a clearer preview and verbose message than a generic function-name description. A one-argument call such as ShouldProcess($target) uses the function name as the operation. A three-argument overload is available when you need to customize the complete message.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
Make the target identify the object or resource and make the operation describe the change: for example, ShouldProcess("User '$UserName'", 'Disable account').
What -WhatIf does
When a caller supplies -WhatIf, ShouldProcess reports the proposed action and returns false. Code inside the guarded branch therefore does not run, while validation and other non-mutating setup can still expose errors.
PS> Set-ExampleThing -Name Demo -WhatIf
What if: Performing the operation "Update" on target "ExampleThing 'Demo'".This preview covers only work that actually passes through your guard. A direct .NET property assignment, file-system API call, database command, or external process is not automatically protected; put that call itself inside the true branch.
How -Confirm and ConfirmImpact interact
-Confirm asks before a guarded operation when the function’s ConfirmImpact meets the caller’s $ConfirmPreference. The documented default impact is Medium. Reserve High for highly disruptive actions, such as reformatting a hard-disk volume, rather than ordinary updates.
Recommended Free Tools
function Reset-ExampleThing {
[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]
param([Parameter(Mandatory)][string] $Name)
$target = "ExampleThing '$Name'"
if ($PSCmdlet.ShouldProcess($target, 'Reset')) {
# Destructive persistent change.
}
}The confirmation prompt can offer Yes, Yes to All, No and No to All. The exact prompt appears only when the impact and preference settings call for confirmation; -WhatIf remains a preview and does not perform the action.
ShouldProcess versus ShouldContinue
| Method | Purpose | -WhatIf |
Interactive requirement | Effect of -Force |
|---|---|---|---|---|
ShouldProcess |
Standard operation check and the source of WhatIf/Confirm behavior. | Reports the action and returns false, skipping the mutation. | Works as the normal confirmation mechanism governed by preferences. | Does not replace or disable this check. |
ShouldContinue |
Optional second, more finely scoped confirmation. | It is reached only after the ShouldProcess check; it is not a substitute for that check. | Requires an interactive prompt; it can throw when no prompt can be shown. | A supplied Force switch should bypass ShouldContinue while retaining ShouldProcess. |
Most cmdlets need only ShouldProcess. Add ShouldContinue when users genuinely need a second decision with a narrower “Yes to All” scope.
function Remove-ExampleThing {
[CmdletBinding(SupportsShouldProcess)]
param(
[Parameter(Mandatory)][string] $Name,
[switch] $Force
)
$target = "ExampleThing '$Name'"
if ($PSCmdlet.ShouldProcess($target, 'Remove')) {
if ($Force -or $PSCmdlet.ShouldContinue(
"Remove $target permanently?", 'Final confirmation')) {
# Persistent removal.
}
}
}Keep calling ShouldProcess even with -Force. Force is only a way to skip the additional interactive confirmation; it must not turn off WhatIf protection.
Module boundaries and preference propagation
Do not assume that $WhatIfPreference or $ConfirmPreference flows through every nested call. Built-in cmdlets, same-scope functions and some call patterns generally behave as expected, but a script module invoked from a function in another script module may not inherit those preferences. Microsoft Learn’s PowerShell deep dive recommends explicitly forwarding WhatIf where relevant and testing—or assuming propagation will fail—when module boundaries are involved.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →For wrappers, expose and pass the common parameters deliberately rather than treating a successful outer preview as proof that a downstream module is protected. Test the composed modules in the PowerShell version and host where they will run.
Rank #4
- Book - powershell for sysadmins: workflow automation made easy
- Language: english
- Binding: paperback
Static analysis catches missing support
UseShouldProcessForStateChangingFunctions
PSScriptAnalyzer’s warning rule flags functions using state-changing verbs without ShouldProcess support. Its listed verbs include New, Set, Remove, Start, Stop, Restart, Reset and Update. The rule is always enabled.
UseSupportsShouldProcess
This warning rule discourages manually declaring WhatIf and Confirm parameters and recommends [CmdletBinding(SupportsShouldProcess)]. It is also always enabled.
Invoke-ScriptAnalyzer -Path ./MyModule.psm1Use analyzer output as a review prompt, not as proof that every mutation is covered. Inspect every branch that can persist a change, including helper functions, direct .NET calls and external programs.
Best Value
- Used Book in Good Condition
Review checklist before shipping
- Add
SupportsShouldProcessto every state-changing advanced function. - Do not declare
WhatIforConfirmyourself. - Resolve and validate inputs before the guard, then place each persistent mutation inside the true branch of
ShouldProcess. - Use target and operation text that makes a preview understandable.
- Set
ConfirmImpactdeliberately; useHighonly for highly disruptive operations. - Add
ShouldContinueonly for a real second confirmation need, and provide-Forceto bypass that prompt while retaining ShouldProcess. - Check direct .NET and external-process mutations separately.
- Test wrappers and cross-script-module calls for WhatIf and Confirm propagation.
- Run PSScriptAnalyzer and address both ShouldProcess-related warnings.
Official guidance
“In the cmdlet code, call the System.Management.Automation.Cmdlet.ShouldProcess method before the operation that changes the system is performed.”
Microsoft Learn, “Requesting Confirmation from Cmdlets” (last updated 2026-04-08)
The behavior described here follows the PowerShell 7.5 and 7.6 documentation and the PSScriptAnalyzer guidance current through 2026. Validate prompts, previews, external operations and module composition in your target host and PowerShell version.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
