Weekend Scripter: Easily Add Whatif Support to Your PowerShell Functions

Summary: Microsoft Scripting Guy, Ed Wilson, shows how to easily add whatif support to your Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. I love demoing Windows PowerShell to people who have never seen it—and believe it or not, there are still IT Pros who have not seen or used Windows PowerShell. Most people have heard of it by now (if they are in the business), but there is still a surprisingly large number of people who do not use Windows PowerShell. One of the features that generally gets ooohs and ahhhhs (and at times even applause) is the whatif parameter.

I generally tell people that they no longer have to run a command to see what it will do. Often I ask for a show of hands to see how many people have run a command and they did not know what it would do. Not surprisingly, the number of hands that goes up is large. Scarier, is when I ask who has run a command on a production system, and they were not certain what it would do. This is not a sign of carelessness, but rather a sign of desperation—the server is down, you go to TechNet, and it says to fix the problem, run this cryptic command. You do it and hope for the best. But what if there was a type-o on that page? With Windows PowerShell, this is no longer a concern because you can use whatif.

Adding support for the whatif parameter

One of the great features of Windows PowerShell is using the whatif parameter on cmdlets that change the system state, such as the Stop-Service or the Stop-Process cmdlets. In fact, by consistently utilizing the whatif switched parameter, it is possible to avoid many inadvertent system outages. As a Windows PowerShell best practice, you should also implement the whatif parameter in your advanced functions. In the past, this meant creating special parameters, and adding lots of extra code to handle the output. Now, it requires a single line of code.

Note    [cmdletbinding()] appears with empty parentheses because there are other things, such as SupportsShouldProcess, that can appear between the parentheses.

The following function illustrates setting SupportsShouldProcess to True inside the parentheses of the cmdletbinding attribute.

function my-function




 md $path


Now when you call the function with the whatif switched parameter, a message appears in the output detailing the exact behavior the cmdlet takes when run without the whatif parameter. This is shown in the image that follows.

Image of command output

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy 

Comments (8)

  1. jrv says:

    Good series.  Advanced functions have many reat features.  It may take a while to cover them all and I am sure few of us have found all of the features.  Can't wait to see more.

    # side effects

    function my-function{



      #do nothing


    my-function -?

  2. K_Schulte says:

    A short but informative blog article!

    This series should be continued 🙂


  3. Bigteddy says:

    Excellent info, Ed.  As jrv says, this is good stuff!

  4. Ed Wilson says:

    @JRV @BigTeddy I am glad you are enjoying the articles. Yes there are a LOT of features that advanced functions expose. cmdletbinding exposes some great features, AND is easy to do. This is the "low hanging fruit" aspect … that is it is the single change easiest to make, that pays the biggest dividends.

  5. Anders Rask says:

    Be aware though, that this will only work if the cmdlet or advanced function supports WhatIf !
    If you are coding your own function, you need to implement the logic yourself, using the $pscmdlet.ShouldProcess() method.
    if( $pscmdlet.ShouldProcess($list.Title, "Update") )

    will output
    What if: Performing the operation "Update" on target "MyList".

  6. Phil95 says:

    This seems great, but not always works as expected. Hereunder an example where the first function does not work whilst the second one -as given by article- works perfectly.

    Function test-bindings {
    param([String]$AdapterName, [Boolean]$Enabled)

    Set-NetAdapterBinding -Name $AdapterName -ComponentID ms_tcpip6 -Enabled $Enabled

    Function test-makedir {

    MD $Path

    $NAC = ((get-netadapter)[0]).Name
    test-bindings -AdapterName $NAC -Enabled $False -Whatif [tag:does] not work as expected
    test-makedir -Path ‘C:UsersDocumentstestbinding’ -Whatif [tag:OK] !!
    ‘This is the end, my friend ‘ + $env:username

    I’d like to write some function to set many parameters of NIC, and be able to test them with the -whatif switch.
    How must I proceed ?


  7. Me says:

    Missing bits:
    # code to execure

  8. alex says:

    Using [CmdLetBinding(SupportsShouldProcess=$True)] adds -whatif to EVERY commandlet in the script.
    For example, using this technique will break the EMS initialization. How can I make some parts of the code actually running even under global -whatif?

Skip to main content