Creating a Custom Windows 7 Troubleshooting Pack
Windows 7 offers a built-in troubleshooting platform that consolidates the typical user’s support and troubleshooting needs into a single consistent user interface with dozens of specific troubleshooters for common problems.
If you haven’t seen the Troubleshooting Platform in action yet, go ahead and type “troubleshooting” into your Windows 7 start menu and open the Troubleshooting control panel applet.
You can try some of the troubleshooters now. I’ll wait here. One of the easiest ones to repro and use is the “Check for performance issues” troubleshooter. Go ahead and change your power plan to the “Power Saver” plan and run the troubleshooter (while on AC power). The troubleshooter will attempt to detect performance problems for a few seconds, and then it will tell you that you’re using a power plan that can decrease your system’s optimal performance, and even offer to automatically fix the problem by moving you back to the “Balanced” power plan.
The first thing I thought about when I saw this platform in action was: How can I write a troubleshooter myself? How can I use the same consistent user interface to offer users of my software a self-support mechanism? (…And if you currently have any support costs at all for your own software, you must be asking yourself the same questions.)
Fortunately, writing a troubleshooting pack is fairly easy. There’s a neat tool that ships with the Windows 7 SDK called the Troubleshooting Pack Designer. You’ll find it in your SDK root under the Bin\TSPDesigner folder.
What I’m going to do in this short blog post is show you how to create a simple troubleshooting pack that will troubleshoot a very simple problem—if there is no folder named Temp in the C:\ root drive, it will create that folder automatically. You can imagine how this can be useful for legacy applications that disregard UAC and create folders all over the place.
To begin, I’ll click the new project icon and choose a location for the troubleshooting pack that I’m creating.
Next, there are all kinds of details to fill in, including the project name, description and privacy URL for the troubleshooter users. Next, we need to add a root cause, which is a general title for the thing that the troubleshooting pack can detect. Again we need to fill in some details.
Now it’s time to define the troubleshooter. Again there are some questions to answer first—the troubleshooter might or might not require elevation and might or might not require user interaction. My troubleshooter doesn’t require any of these.
Now we’re going to create a resolver—that’s the part of the troubleshooting pack that actually solves the problem. Again we need to give it a name and a description, and answer a few questions—does the resolver have any adverse side effects, does it have to run elevated, does it need any user interaction.
Finally, we have to define a verifier script—that’s the part that makes sure the problem is gone. In this case, we can reuse the troubleshooter script, so that’s what I’m telling the designer to do.
Now that I’ve defined all the parts of the troubleshooting pack, I need to write the actual code that detects, resolves and verifies the problem. That is done by using the “Edit Root Cause Scripts” link on the left. This opens the PowerShell IDE that ships in Windows 7. The language of choice for the Windows Troubleshooting Platform is PowerShell 2.0, which means that you can easily integrate your existing troubleshooting scripts using the standard .NET facilities or interop mechanisms.
In the troubleshooter script, I’m going to do a very simple check for the existence of the C:\Temp directory (the same script can be reused by the verifier part of the pack because it doesn’t have any side effects). Here’s the code:
$RootCauseID = "NoTempDirectory"
$RootCauseDetected = -not [System.IO.Directory]::Exists("C:\\Temp")
update-diagrootcause -id $RootCauseId -detected $RootCauseDetected
Now let’s move on to the resolver script. Here we’re going to create the C:\Temp directory, nothing more. Here’s the code:
That’s all there’s to it—we now have a troubleshooting pack that is ready for action! One minor thing remaining is to actually sign the troubleshooting pack and then distribute it to your clients, but you can test-run the thing from the designer by clicking the green “Play” button, and voila:
If you look at the output\cab folder under the troubleshooting pack’s root directory (which I chose when creating the project), you’ll find a stand-alone .cab file ready for use.
Double-clicking that file brings us to the troubleshooting pack wizard, first step.
This post was just a brief overview of how easy it is to create a troubleshooting pack. It didn’t feature any sophisticated user interaction (and there are quite a few built-in interactions in the Troubleshooting Platform), so we basically only scratched the surface of this subject.
If there will be interest (and time) I will write more about troubleshooting packs, but in the meantime I suggest that you take a look at the Troubleshooting Pack Designer and learn how to write troubleshooting packs for your own software.