Using [CmdletBinding()] to Add -WhatIf and -Confirm to PowerShell Functions

Add -WhatIf and -Confirm to a PowerShell function

When you need a script that behaves like a built‑in cmdlet, turn it into an advanced function by adding the [CmdletBinding()] attribute. This gives the function automatic access to PowerShell’s common parameters (-WhatIf, -Confirm, -Verbose, -Debug, -ErrorAction) without writing extra code.

Worked example

function Invoke-DemoAction {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Target
    )

    # The action only runs when ShouldProcess returns $true
    if ($PSCmdlet.ShouldProcess($Target, 'Perform action')) {
        Write-Verbose "Starting action on $Target"
        # Replace the line below with the real work you want to do
        # Example: Remove-Item -Path $Target -Force
        Write-Output "Action completed on $Target"
    }
}

How to verify the behavior

1. Run the function with -WhatIf and -Verbose:

   Invoke-DemoAction -Target 'C:\Temp\test.txt' -WhatIf -Verbose

   You should see a verbose message ("Starting action on …") followed by a line that describes what would happen (e.g., "What if: Performing the operation 'Perform action' on target 'C:\Temp\test.txt'"). No file is created or changed.

2. Run the same command without -WhatIf on a safe target:

   Invoke-DemoAction -Target 'C:\Temp\test.txt' -Verbose

   If the file exists, the function writes the verbose message and then outputs "Action completed on …". If you replaced the placeholder with a real command (e.g., Remove-Item), the file would be removed. If nothing happens, check that the ShouldProcess call surrounds the action and that the $Target value matches the argument.

Limits and common mistakes

• Missing ShouldProcess: If you place the action outside the if ($PSCmdlet.ShouldProcess(...)) block, -WhatIf and -Confirm are ignored and the action always runs.
• Using Write-Host: Writing directly to the host bypasses PowerShell’s output streams, so -Verbose and -Debug messages are suppressed and debugging becomes harder.
• Confirm impact: The default impact level is Medium. If you want -Confirm to prompt only for high‑risk actions, set [CmdletBinding(ConfirmImpact='High')] and match the impact in your ShouldProcess call.
• Version requirement: Advanced functions need PowerShell 2.0 or later; they work in Windows PowerShell 5.1, PowerShell 7.x, and PowerShell Core.
• Plain scripts: A script file that lacks the [CmdletBinding()] attribute cannot expose the common parameters; you must wrap the code in a function as shown.

Practical check

# Test WhatIf
Invoke-DemoAction -Target 'C:\Temp\demo.txt' -WhatIf -Verbose
# Test actual execution (use a disposable file)
New-Item -Path 'C:\Temp\demo.txt' -ItemType File -Force | Out-Null
Invoke-DemoAction -Target 'C:\Temp\demo.txt' -Verbose
# Clean up
Remove-Item -Path 'C:\Temp\demo.txt' -Force

If the first call shows a WhatIf message and the second call reports the action completed, the advanced function is working correctly. Adjust the placeholder inside the ShouldProcess block to perform your real task.