Tag Archives: functions

PowerShell Blogging Week: Supporting WhatIf and Confirm

We hope you are enjoying this experiment in community blogging. In today’s contribution I want to demonstrate how you can add support for WhatIf and Confirm to your advanced PowerShell functions. It is actually quite easy, especially if your function is simply calling other PowerShell commands that already support –Whatif and –Confirm. The recommended best practice is that if your function will do anything that changes something, it should support these parameters. Here’s how.

In your function you will need to use the cmdletbinding attribute and specify SupportsShouldProcess.

Beginning with PowerShell 3.0 this is all you need but you will see scripters explicitly setting this to $True.

That’s fine, although personally I find it redundant. If SupportsShouldProcess is listed then by default it is True. There is no need to explicitly set this to $False. Simply omit it. When you add this attribute, you will automatically get the –WhatIf and –Confirm parameters. The best part is that if your function is simply calling PowerShell cmdlets that already support –WhatIf, they will automatically inherit this setting. Here’s a sample function.

The function deletes all files from the %TEMP% folder that have a last modified time older than the last boot up time. As you can see in the help, PowerShell added the necessary parameters.

When I run the function with –Whatif it is passed on to Remove-Item.

It is really that easy. I also automatically get support for –Confirm.

Things gets a little trickier when you want to support WhatIf for a function where your commands don’t natively recognize SupportsShouldProcess. This would be true of any .NET static method or even a command line tool you might be running, to name a few examples. To add your own support you need to invoke the built-in $PSCmdlet object and its ShouldProcess() method. Here’s a simple example.

This function hypothetically is going to perform some action on a folder and I’m simply displaying the folder name in upper case. The important part is the If statement. This is the bare minimum that you need. If you specify –WhatIf you’ll be prompted.

The operation will be the name of your script or function. The target is the ShouldProcess parameter value which in my example is the path. But you can provide more specific information by specifying ShouldProcess parameters for the target and action. Here’s a revised function.

You must have the code for ShouldProcess otherwise even if you set the cmdletbinding attribute, PowerShell won’t know which commands need WhatIf. You can also have as many ShouldProcess statements as you need.

When it comes to confirmation, things get a little trickier and it might depend on what you really need. As you saw above, any cmdlet that supports –Confirm should automatically inherit the setting. This works because there is another cmdletbinding attribute called ConfirmImpact which has a default value of Medium. Other options are Low and High. My first function could also have been written like this:

Confirmation happens by comparing the value of ConfirmImpact with the built-in $ConfirmPreference variable which has a default value of High. If the value of $ConfirmPreference is equal to or greater than ConfirmImpact, PowerShell will prompt for confirmation. Let’s test this out.

Notice that I am also using for WhatIf. In this function the ConfirmImpact is set to high which means PowerShell will always prompt.

If I edit the function and change to ConfirmImpact to Medium or Low, then PowerShell will only confirm if I ask.

You don’t have to specify anything for cmdletbinding. If you know you always want confirmation you can do something like this:

Notice the use of the ShouldContinue method. When I run this function, PowerShell will always prompt for confirmation.

I also added a switch parameter called Force so that if it is specified, the user is not prompted for confirmation.

The downside to this approach is that help doesn’t show anything.

Perhaps in special cases this is what you want. Personally, I think you are better off using the cmdletbinding attributes as I did for my Set-Folder6 example.

Adding support for WhatIf and Confirm doesn’t take much effort and it will take your advanced function to the next level.

This post is part of the PowerShell Blogging Week series on Windows PowerShell Advanced Functions, a series of coordinated posts designed to provide a comprehensive view of a particular topic.

Other articles in this series:

We hope you found our work worth your time.

Friday Fun: Out-ConditionalColor

Last week I posted a Friday Fun article on parsing results from Invoke-Webrequest and displaying matching strings in color so that the book titles I’m interested in stand out. But the more I thought about it I realized I should take this a step further. The problem with Write-Host is that it doesn’t write anything to the pipeline which is why we typically frown upon its use. Although being able to use color to highlight something is very cool. I wanted color and pipelined output. Here’s my result.

This function only really works in the PowerShell console. It is designed to accept any PowerShell input. The function also takes parameters that help it write matching objects in the specified color. The easy way to use the function is to specify a property and a hashtable. The hashtable key is the value you want to match in the input and the key is the color you want to use. The function processes each object as it comes in and if the property matches the value it sets the foreground color of the console to the specified value.

If it doesn’t match then the foreground color essentially remains the same. This means I can run a command like this:

And get a result like this:

Any time the process name is equal to ‘chrome’ I display that object in yellow. You can also have multiple entries.

I mentioned match earlier but it is really a simple equality test. However, I also added code so that you could be even more granular.
You can also create what I refer to as a complex hashtable. This must be an ordered hashtable, which means you must be running PowerShell 3.0. Define a hashtable like this:

This is a little tricky. The hashtable key is a scriptblock of the object property you want to watch and some operator comparison. The value is the console color you want to use for the match. Use $psitem to represent the current object in the pipeline. The reason for the ordered hashtable is because the keys are processed in an If/ElseIf fashion so make sure you get things in the right order.

The function breaks apart the hashtable and builds a here string of the If/ElseIf structure in the Begin scriptblock.

The here string includes the commands to set the host foreground color. Then in the Process scriptblock I use Invoke-Expression to execute it.

But now I can do this.

When using a complex hashtable, there’s no need to specify a property. What’s great about all of this is that if you want to see the color output and still save the results, use the common -Outvariable parameter with Out-Conditionalcolor.

$P won’t be colorized (unless I run it through the function again), but I still have the data.

There are some limitations. Like any Out cmdlet, this must be the last command in your pipelined expression. Technically you could sort or filter after my function, but it will lose the conditional coloring. Unlike the other Out cmdlets, you cannot piped any formatted data to it.

The whole point of the function is to provide a means of adding some visual references to your PowerShell data.
occ-basic3I sincerely hope you’ll try this out and let me know what you think.

MSDevWNY PowerShell Advanced Functions

talkbubble-v3Last night I presented for the MSDevWNY user group in the Buffalo, NY area. They were an interested and enthusiastic audience and I think we could have spent another few hours talking about PowerShell. My presentation was one I’ve given before on Advanced PowerShell functions. I promised the group a copy of my slides and demos, including the scripts we didn’t have time to get to. But the material is open to anyone.

If you want to learn more about PowerShell scripting and toolmaking then naturally the best book is Learn PowerShell Toolmaking in a Month of Lunches.

Download the PowerShell Advanced Functions v3 zip file.

Thanks to Rich and everyone in Buffalo and I look forward to a return visit.