Where and why to use Write-Debug

Hello again!

I wanted to write an article on write an article on write-debug for awhile so here it is.

Just to start, you can get more info on the cmdlet here: http://technet.microsoft.com/en-us/library/hh849969.aspx or by typing
get-help write-debug -full

When you use write-debug in a script/function it doesn’t do anything by default. Debug messages just kind of sit there until you either modify your $DebugPreference or activate the -debug switch when calling a script/function.

Quick side note here if you don’t know what Common parameters are check out the About_common_parameters help topic or view the link here: http://technet.microsoft.com/en-us/library/hh847884.aspx

Debug messages create breakpoints that are activated when you call a script/function with the -debug switch activated or the $DebugPreference set to ‘inquire’. It gives you a handy way to drop into debug mode and can provide you some valuable information while you’re at it. Generally I try and stick write debug after I’ve defined one or more variables, right before I start an operation I’m worried I may have issues with, and right after significant operations. Here’s a simple example:

function Get-FilewithDebug
Write-Verbose "Starting script"
Write-Debug "`$path is: $path"
$return = Get-ChildItem -Path $path -Filter *.exe -Recurse -Force
Write-Debug "`$return has $($return.count) items"

When I run that function with -debug I get the following results:

[C:\git] > Get-FilewithDebug -path C:\Users\jmorg_000\ -Debug
DEBUG: $path is: C:\Users\jmorg_000\

Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"):

From here I can drop into Debug mode and look at the $path variable, or any other variable or object state in the context of the function at that moment. It’s fairly straightforward in this example but it can be invaluable when you’re dealing with more complex scripts or functions. Assuming I’m happy with what I see in the $path variable I’ll continue on to the next breakpoint. Y will allow the operation to continue

At the second break I’ll hop into debug mode.

DEBUG: $return has 226 items

Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): s
[C:\git] >> $return.count
[C:\git] >> exit

In the second example the Debug output tells me I have 226 .exe files in $return, I go ahead and check the count on $return and it really is 226. Perfect. I can do anything else I like at that point, I can look at some of the folders I didn’t have access to. I can check all the extensions in $return. I can look at my execution context, whatever. The point is that adding write-debug into your scripts gives you a handy way to break into debug mode.

Well I hope that was useful, I certainly had fun writing it and I definitely think adding write-debug to your scripts and functions is well worth the effort.

This entry was posted in PowerShell and tagged , , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s