Using PowerShell WhatIf So You Don’t Break Stuff

PowerShell is a powerful scripting language and automation tool. You make changes for one thing or hundreds of things using the same script or function. One amazing feature to add to your functions is the PowerShell -WhatIf parameter. This parameter tells you what the function is going to do before you execute it for real.

In this post, you will learn how to add the PowerShell -WhatIf parameter to your functions using easy-to-follow examples.

What is the PowerShell -WhatIf Parameter?

The PowerShell -WhatIf parameter enables the function to simulate what it will do instead of actually executing. Testing the function in this way allows you to understand the impact of the command. Think of it as a safety net to ensure you don’t break stuff.

For example, you want to remove mailboxes with the string “Shared” in the name. Adding -WhatIf to Remove-Mailbox allows you to verify which mailboxes will be removed before executing the command for real.

Get-Mailbox -Identity "*Shared*" | Remove-Mailbox -WhatIf

By adding -WhatIf to the Remove-Mailbox command, you verify which mailboxes the command will remove. The command doesn’t actually make any changes. It just lets you know what would have happened.

However, the PowerShell -WhatIf parameter does not always guarantee the command will execute successfully. You can still run into issues with permissions or another component that prevents the command from executing successfully. Adding -WhatIf will show what will happen given everything else goes correctly.

You add the PowerShell -WhatIf parameter to functions that have the potential to make changes. Some examples of PowerShell verbs for these commands include Set and Remove. If you are using PSScriptAnalyzer to check your functions and scripts for best practices, one of its rules is to add the PowerShell -WhatIf functionality to these functions if it finds it.

Here I am running PSScriptAnalyzer against the function you will write later in this article. Note the output saying the function is using a verb that makes changes, so the function should support ‘ShouldProcess’ (more on this later).

Adding ShouldProcess to Your PowerShell Code

To use the -WhatIf parameter, you add the SupportsShouldProcess attribute to the [CmdletBinding()] section of your code. The CmdletBinding attribute adds capabilities to functions so the function works more like a compiled cmdlet. These capabilities include automatic parameters like Verbose, Debug, and the WhatIf parameter.

Here is an example function definition that sets a user’s telephone number in Azure Active Directory. The function includes:

• CmdletBinding attribute with SupportsShouldProcess
• Two parameters for the user principal name and phone number
• Code that sets the phone number

Surprisingly enough, the Set-AzureAdUser cmdlet does not include the -WhatIf parameter. Since it is not included, I thought this would be a good example to wrap into a specific function for setting a user’s telephone number.

function Set-UserPhoneNumber {
    [CmdletBinding(
        SupportsShouldProcess
    )]
    param(
        [Parameter(Mandatory)]
        [string]
        $UserPrincipalName,
        [Parameter(Mandatory)]
        [string]
        $PhoneNumber
    )
    Set-AzureAdUser -ObjectId $UserPrincipalName -TelephoneNumber $PhoneNumber
}

Adding SupportsShouldProcess to CmdletBinding is not enough. You wrap the code that is making the change into an if block. The if block checks if you specified the -WhatIf parameter by checking the automatic variable $PSCmdlet and the ShouldProcess method. This tells the function to not execute the code in the if block but to display what the function would have done.

The ShouldProcess method accepts multiple arguments, but only one is required. For a single argument, specify the target of the action, such as the user account or file name.

Here is the Set-AzureAdUser command wrapped in this if statement with $UserPrincipalName as the argument for ShouldProcess:

if ($PSCmdlet.ShouldProcess($UserPrincipalName)) {
    Set-AzureAdUser -ObjectId $UserPrincipalName -TelephoneNumber $PhoneNumber
}

Here is the output of the function when using the -WhatIf parameter. The output message contains the name of the function and the target of the action, in this case, the user principal name.

Customizing the “What if” Message

The ShouldProcess method accepts more than one argument to customize the “What if” message. In the above example, the first argument specified the target being modified by the command. The next argument customizes the operation name.

This example gives more detailed information on what phone number (the operation) is being assigned to the user (the target). Note the “Assigning $PhoneNumber” appear as the operation in the output screenshot.

if ($PSCmdlet.ShouldProcess($UserPrincipalName, "Assigning $PhoneNumber")) {
    Set-AzureAdUser -ObjectId $UserPrincipalName -TelephoneNumber $PhoneNumber
}

To fully customize the message, insert a string in the first argument place while maintaining the existing arguments in the second and third slot.

if ($PSCmdlet.ShouldProcess("Assigning the number $PhoneNumber to user $UserPrincipalName", $UserPrincipalName, "Assigning $PhoneNumber")) {
    Set-AzureAdUser -ObjectId $UserPrincipalName -TelephoneNumber $PhoneNumber
}

Closing

Adding the PowerShell -WhatIf parameter takes a few extra lines of code but provides invaluable functionality to your code. If your script or function has complex logic that branches based on different criteria, using what if can show what the code will do before running it for real.

Enjoyed this article? Check out more of my PowerShell content!

Additional Reading:
Cmdlet.ShouldProcess Method | Microsoft Docs
About Functions CmdletBindingAttribute: SupportsShouldProcess | Microsoft Docs