The PowerShell WhatIf parameter

PowerShell has built-in functionality for all of its cmdlets and advanced functions, known as the WhatIf parameter. The WhatIf parameter allows you to see what your script or function would have done if it were to have run.

Have you ever hit the Enter key on the keyboard and immediately regretted the decision? We've all been there. We've built this beautiful script that automates all kinds of tasks, and we're excited to try it out. The script runs while you forgot a few minor details, which unfortunately leads to user account deletions, mailbox permission problems, servers going down… You get the drift here.

It'd be good to know what the code would have done if it were actually to have run. Next time, instead of testing in production, why not incorporate WhatIf functionality into your code?

Granted, it's up to you to add this functionality into your code, so we've still got human error to worry about. But it's a safe step in the right direction.

Let's create an example of a function that would be catastrophic if it ran.

Let's say this function is part of a large script you've created to clean up old user accounts. One day you're tired and accidentally forget a single keystroke. Instead of typing 30 to represent cleaning up users older than 30 days, you miss the zero and type 3 instead.

Your script doesn't know you missed a keystroke and happily goes along and begins removing all Active Directory users older than three days. I'm sure a lot of your user accounts fall in this category. Adding a failsafe could have prevented this. One of those failsafes is WhatIf support.

To make this function a little safer, I'm going to add WhatIf support. This will allow me to invoke this function using the WhatIf parameter.

Adding WhatIf functionality to your function requires two steps.

  • Adding the SupportsShouldProcess keyword
  • Adding the $PSCmdlet.ShouldProcess conditional statement

Without both of these requirements, WhatIf will not work. First, we must add SupportsShouldProcess inside of CmdletBinding() at the top. This tells PowerShell that this function is going to be an advanced function that supports the WhatIf parameter.

Next, we must add a conditional step right before the potentially destructive action. We do this by checking for WhatIf usage. And to do that, we monitor the output of the ShouldProcess() method on the automatic $PSCmdlet variable. The ShouldProcess() method has a few arguments, but the most useful look like this:

You can see here that we specify the target of the action we're about to perform and also a description of the action we'll be performing. If we use WhatIf when calling this function, this method will return $true.

For our example, we're removing an Active Directory user, so our target will be the individual user account, and our action will be 'Remove.' We can show this then by passing this information to the ShouldProcess() method.

Notice that I've changed up the code a bit in our final function. This allows me to confirm each user account. If you'd rather not see every user account it will potentially remove, you could have left it as is. However, when I run the function with the WhatIf parameter now, it doesn't do a thing. It just returns text to the console of what the function would have done if it ran without WhatIf.

WhatIf example

WhatIf example

Join the 4sysops PowerShell group!

Your question was not answered? Ask in the forum!

  1. Jim 3 years ago

    I'm curious - you commented out the line that does the actual remove:

    #$_ | Remove-AdUser -Confirm:$false

    I'll look up the details later, but is that part of adding the What-If functionality?


  2. Andrew 9 months ago

    "If we use WhatIf when calling this function, this method will return $true." Isn't the opposite true? Using WhatIf should prevent the critical block from executing.


Leave a reply

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2020


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account