PowerShell Pipeline

Provide Safe Scripting by Adding WhatIf Support

Be sure something won't break with your code with this handy parameter.

• By Boe Prox
• 08/20/2015

Have you ever been in a position where you weren't sure that the command that you were going to run was really going to work in a way that you had hoped? Such as querying for a process and then,  in the same one liner, wanting to kill that process? If you were comfortable with your query and just went right for it without a second thought, well that's great! But if you wanted to be sure (I know I always want to be sure) then with most cmdlets that perform some sort of change action whether it is setting, creating or deleting, you want to make use of an amazing parameter that should be available called –WhatIf. Let's just assume that I wanted to stop some process that started with S. Probably not the best idea running around but luckily I know enough to use –WhatIf with Stop-Process to see what might happen.

Get-Process s*  | Stop-Process  -WhatIf 

Good thing I just didn't let it run without some training wheels. As you can see, instead of just following through and stopping all of these processes, I can see what would have happened had I not used –WhatIf. Pretty nice to see what kind of damage that would have been done.

While having this available out of the box with our cmdlets is great, we need to make sure that anything that has been written by ourselves should abide by this as well. In fact, if you are building a function that makes any sort of change, it should absolutely provide support for –WhatIf.  By not providing this type of support, we are just sending out potentially dangerous commands into the wild and potentially breaking the trust of those who would come to expect this to be available in a command based on what they have seen with what is currently available with PowerShell.

So with all of that said, how do we actually do this? The first step is to ensure that in your function that [cmdletbinding()] and Param() have been defined in the function body.

Function Invoke-PowerShellCrash  { 

  [cmdletbinding()]

  Param  ()

  ...

} 

Within [cmdletbinding()], we have to set the SupportsShouldProcess attribute to True to let PowerShell know that this function will support –WhatIf as a parameter. This does not mean that we have configured –WhatIf support at this point in time.

Function Invoke-PowerShellCrash  { 

  [cmdletbinding(

  SupportsShouldProcess = $True 

  )]

  Param  ()

  ...

} 

Now I am assuming some backwards compatibility with V2, otherwise you can just leave out the = $True part and just specify SupportsShouldProcess instead.

Now comes the fun part. We will now begin the process of putting together the code needed to ensure that we actually do use –WhatIf when specified as a parameter. We first need to call $PSCmdlet.ShouldProcess(),  which will check to see if –WhatIf has been used and then, based on the parameters within ShouldProcess, display some sort of information to the user.

What I am most concerned with is ensuring that we specify both a target, that is the object that this will be run against, and a short caption so the user running this commands knows exactly what is happening.

If ($PSCmdlet.ShouldProcess($PID,'Crashing PowerShell')) {

  [environment]::FailFast('Invoked  Crash')

} 

In this case, I am going to specify the process ID of the current PowerShell console that this is being run on and letting the user know that this will crash the console. Yea, it's probably not something you would ever put out in production, but it provides a nice example of protecting not only yourself, but those who are using your code by seeing what would happen.

Invoke-PowerShellCrash -WhatIf 

Works like a champ! Had I not done this, well, this is what you would end up seeing instead:

Invoke-PowerShellCrash -Verbose 

Whoops! Did I mention that providing –WhatIf support also throws in a free Verbose output as well for this particular action? How great is that?

Another thing to mention is that adding the SupportsShouldProcess=$True means that any cmdlets that already have this functionality will automatically use it if you happen to specify –WhatIf as show in the examples below.

Function Stop-ProcessV2  {

  [cmdletbinding(

  SupportsShouldProcess = $True 

  )]

  Param (

  [parameter(ValueFromPipelineByPropertyName=$True)]

  [Alias('Id')]

  [int]$ProcessID

  )

  Stop-Process  -Id $ProcessID

  }

Get-Process -Name System | Stop-ProcessV2 -WhatIf 

This is important in case you have other parts of your code which maybe should run regardless of the –WhatIf preference and should be handled accordingly.

With that you now have the skill set needed to move forward and update all of your scripts/functions that have the ability to modify, remove or create new things and now ensure that these have the necessary safety net that it deserves!