Prof. Powershell

What If My Script Gets Me Fired?

Take the guesswork out of your scripts and find out the common risks via the -Whatif parameter.

• By Jeffery Hicks
• 08/23/2011

Windows PowerShell can be dangerously easy to use. If you aren't careful you can easily delete thousands of files, stop a critical service or disable the CEO's account. In some circles, those events are known as "career-limiting moves." Instead, you want to take advantage of the common risk parameters in Windows PowerShell, like -WhatIf.

Any cmdlet that will change the state of a system is supposed to support the -WhatIf parameter:

PS C:\> get-service winmgmt | stop-service -whatif

What if: Performing operation "Stop-Service" on Target "Windows Management Instrumentation (winmgmt)".

But you can also include support for this parameter in your PowerShell scripts and functions using the cmdletbinding attribute. At the beginning of your script or function you'll need this:

#requires -version 2.0

[cmdletbinding(SupportsShouldProcess=$True)]

Param([string]$Path)
...

First, if your script has any cmdlets that support -WhatIf, they will automatically include it if you run your script with -WhatIf. For example:

PS C:\> c:\scripts\fixfiles.ps1 -whatif

If the script file includes cmdlets like Remove-Item, the expressions will automatically include -WhatIf, thus providing a little sanity check before I run the script for real. But what if you are running code that you also want to test with -WhatIf but the cmdlet you are using doesn't support it? Or you are writing commands using [ADSI] or other types of objects. Here's how.

I have a script that is going to import a very large CSV file and do something with the data, but I want to test and verify parts of my script using -Whatif. Import-CSV doesn't support the parameter. Instead, I can accomplish this using the special $pscmdlet object:

if ($pscmdlet.ShouldProcess($path)) {
    #import the CSV
    $data=Import-CSV -Path $path

}

Because ShouldProcess is set to $True in the cmdletbinding attribute, I'll get a WhatIf statement for whatever value is inside the method parentheses. In my example, the name of the CSV file.

PS C:\> S:\Demo-ShouldProcess.ps1 C:\work\Fabrikam-2500-NewUsers.csv -whatif

What if: Performing operation "Demo-ShouldProcess.ps1" on Target "C:\work\Fabrikam-2500-NewUsers.csv".

If I run the script without -Whatif, the code within the IF statement will execute -- that is, it'll run the Import-CSV command. You can have as many of these ShouldProcess checks as you need in your script.

So if your script has the potential to "open up new career opportunities" or you merely like maintaining your sanity, incorporate ShouldProcess into your PowerShell work and enjoy your job.