To run an inbox troubleshooter that ships with Windows 7 from the command line use this command

msdt.exe /id <diagnostic_id>

Example: msdt.exe /id NetworkDiagnosticsWeb

To run a custom-built troubleshooter stored locally use this command line

msdt.exe /path <path_to_troubleshooter>

Example: msdt.exe /path c:\troubleshooters\myTroubleshooter

or, if the troubleshooter is a .diagcab file

msdt.exe /cab <path_to_diagcab>

Example: msdt.exe /cab c:\troubleshooters\myTroubleshooter.diagcab

Starting troubleshooters from the command line is really powerful when you combine it with your own experiences running on Windows 7.  Application developers can take advantage of these troubleshooters to help their customers fix problems that may prevent them from getting the best possible experience.  For example, and application which requires internet connectivity can invoke the Windows 7 Networking troubleshooter rather than presenting a error message that the network isn’t available.  To accomplish this, all the developer needs to do is run the “msdt.exe /id NetworkDiagnosticsWeb” command line.  The troubleshooter will take care of the rest.

Here is a short list of troubleshooter IDs to get you started, the rest can be found here.

Enjoy!

-mb

Method 1: Reuse the Windows “Devices” Troubleshooting Pack

This is definitely the method I’d recommend.  It doesn’t take a lot of effort and you can get really good results.  Windows 7 includes a great devices troubleshooter that can do much more than just uninstall and reinstall devices, and you’ll get all that extra goodness for free!  Since it’s included with Windows 7 you know it’ll be there.  All we need to do is tap into that workflow; let’s look at how you can do that.

If you don’t know which device is having problems you can just launch the device troubleshooter and it’ll try to figure it out.  Launching this Troubleshooting Pack from the command line is simple, just type the following command.  This is identical to launching the Troubleshooting Pack from the Troubleshooting Control Panel. 

msdt.exe /id DeviceDiagnostic /skip true

If there is a specific device that’s causing you problems you can pass the PNPDeviceID for that device to the Troubleshooting Pack.  To do this we must change the command line slightly.  We’ve added the “/param” command line argument so we can pass in the specific PNPDeviceID of the problem device.  Obviously, you need to know the PNPDeviceID for the problem device for this to be useful.  This is identical to right-clicking a device in Devices and Printers and selecting Troubleshoot.

msdt.exe /id DeviceDiagnostic /param "IT_SelectDevice=[PNPDeviceID]" /skip true

Example:
msdt.exe /id DeviceDiagnostic /param "IT_SelectDevice=PCI\VEN_8086&DEV_27D8&SUBSYS_380217AA&REV_02\3&21436425&0&D8" /skip true

This is the best approach for general device issues.  It’ll enable devices that have been disabled, search for drivers, and address several other potential problems. 

Method 2: Build an Uninstall/Reinstall Troubleshooting Pack

The second way to uninstall and reinstall a device is to build your own Troubleshooting Pack.  This is more work but will give you complete control over the experience. 

The trick here is that while PowerShell gives you tons of great tools to find devices and check for problems, it doesn’t give you an obvious method to actually uninstall and reinstall the device.  In an earlier post I showed you how to access Win32 APIs from PowerShell and that’s exactly what we need here.  Coincidentally, the Win32 part of that example already has the code we need to reinstall a device, so all we need is some code to uninstall the device.

Rather than just post the uninstall/reinstall code, I thought I’d share with you a complete Troubleshooting Pack sample that’ll show you how to uninstall and reinstall a device.  It enumerates all PCI devices and displays them in a list, so you can select the device to remove.  You can also manually specify the PNPDeviceID of the device you want to work with.  This sample requires the latest version of the Windows Troubleshooting Pack Designer, which you can download here.  Unzip the sample into your “Documents\Troubleshooting Packs” folder and open it in the Troubleshooting Pack Designer.

So there you have it. Two ways to manage devices from within a Troubleshooting Pack.  Pick the method that works best for your environment  and end users.  Drop me a comment if you find this useful or would like to see other examples.

-mb

I’ve got an hour to kill, so I thought I’d take a moment to say thank you to everyone who attended Tech Ed 2010.  I’d like to extend a special thank you to everyone that attended my Windows Troubleshooting Platform interactive session, swung by to chat about troubleshooting at the Windows Manageability booth, or flagged me down during the event.  The interest shown towards the Windows Troubleshooting Platform surpassed all my expectations! 

I got some great feedback from everyone and will be following up as best I can, but I didn’t get the opportunity to connect with everyone.  Many of you were turned away from the session because it was full and believe me when I say that nobody was more surprised than I!  Well, I want to keep that interest alive.  For those of you that weren’t able attend I highly recommend viewing the “Building Troubleshooters” session I presented for the Windows Summit 2010.  Registration is free and it’ll help bring you up to speed.  Those of you that were able to attend may find it useful as well.  It includes some more in-depth examples of how to use the Windows Troubleshooting Platform to reduce support costs. 

If you have a question you weren’t able to ask during the event please feel free to drop me a line here on the MSDN blog and I’ll do my best to answer them.

Thanks everyone!

-mb

Windows Troubleshooting Platform Quick Reference.pdf

-mb

This sample is built using the latest version of the Windows Troubleshooting Pack Designer, which you can get by installing the Windows 7 SDK version 7.1 

DirectX_Troubleshooting_Pack.zip

I've attached a sample DiagCab file that illustrates this concept by combining the Windows 7 maintenance, audio, printer, and aero troubleshooters into one meta-pack.   

The contents of the DiagCab is quite simple.  It contains one file called "metapack.diagcfg" which defines the meta-pack.  The contents of the file is provided below.  Transforming this file into a meta-pack is simply a matter of cabbing up the file and changing the extension from ".cab" to ".diagcab". 

<?xml version="1.0" encoding="utf-8"?> <PackageConfiguration xmlns="https://www.microsoft.com/schemas/dcm/configuration/2008">     <Execution>         <Package Path="%windir%\diagnostics\scheduled\Maintenance"/>         <Package Path="%windir%\diagnostics\system\audio"/>         <Package Path="%windir%\diagnostics\system\printer"/>         <Package Path="%windir%\diagnostics\system\aero"/>     </Execution> </PackageConfiguration>

If you wanted to extend a Windows 7 Troubleshooting Pack then the XML and directory structure would look something like this.  Note that the first package entry points to a folder called "MyAppDiag"; this is the folder that contains your completed diagnostic, which must be included.  Cab the whole thing up, rename to .diagcab, and you're ready to go!

Contents of .DiagCfg

Directory Structure of .DiagCab

.\Metapack.diagcfg .\MyAppDiag .\MyAppDiag\DiagPackage.cat .\MyAppDiag\MyAppDiag.diagpkg .\MyAppDiag\*.ps1

-mb

MetaPack.diagcab

One of my "bad habits" is to use .NET methods instead of native PowerShell cmdlets.  Even now I still find myself using [System.IO.File]::Exists() instead of Test-Path; it's just what pops into my head when I think about that task.  I call this a bad habit because some of the folks I interact with aren't C# developers and don't intuitively understand what's going on when there is inline .NET calls all over the place.  Here's an example of what I'm talking about.  Both these functions do the same thing; depending on your background you may gravitate towards one or the other.  Where possible, I recommend using the native PowerShell cmdlet as it'll help other PowerShell users understand what's going on. 

This style of inline .NET call is pretty convenient when you only need one or two static methods, but what about something more complex?  What if you need to call a Win32 API?  Well, you're in luck, because PowerShell provides a method to get you on your way.  You can use the PowerShell SDK to build a custom cmdlet, but is there another way?  Yes, there is! 

Let's say that you're building a Windows Troubleshooting Pack that's designed to resolve problems with your device.  One of the manual troubleshooting steps you're likely to perform is to check the device in Device Manager for errors, then uninstall and reinstall the device.  In order to do this in your troubleshooter you need to be able to:

1. Identify the device
2. Get its state (ConfigManagerErrorCode for those familiar with accessing devices using WMI)
3. Uninstall the device
4. Reinstall the device

In most cases you'll be able to do the first two tasks directly from PowerShell by using WMI.  Uninstalling and reinstalling the device is a bit more complicated, you'll need to call some Win32 APIs to get that done.  So let's take a look at how that works in PowerShell and the Windows Troubleshooting Platform.  Conceptually, the process looks like this:

1. Identify the Win32 APIs you need to perform this task
2. Create a C#/VB.NET class that wraps the Win32 APIs
3. Bring your wrapper class into PowerShell
4. Call the methods defined in your wrapper class from PowerShell

I'm going to skip the uninstall step and focus on the reinstall.  The concept related to accessing Win32 APIs is identical, but uninstall requires us to do steps one and two first.  For the purposes of this example we can manually do steps 1-3 and code only the reinstall. 

Step 1: Identify the Win32 APIs you need to perform this task

MSDN is your friend here.  In this case we need 3 Win32 APIs:

1. CM_Locate_DevNode_Ex
2. CM_Reenumerate_DevNode_Ex
3. CMP_WaitNoPendingInstallEvents

Step 2: Create a C#/VB.NET class that wraps the Win32 APIs

This is where you'll spend most of your time and why I'd recommend doing this work inside Visual Studio where you have great debugging tools.  To save time I've included the entire wrapper source below in C#.  Paste this into Visual Studio, save, and do a quick build to make sure there aren't any errors.

Step 3: Bring your wrapper class into PowerShell

Now it's time to get our wrapper into PowerShell.  You have a few options here; include as an assembly, or include as source; your scenario and business needs may lend itself to one method more than the other.  For this example we're going to include our wrapper as source.  Obviously, including our wrapper as source code means that it’s readable by anyone who opens the PowerShell script in a text editor.  Including as source works particularly well for short snippets like this.  Regardless of the method, you'll be using the Add-Type cmdlet, which will do all the heavy lifting for us.

I've created a new function in my PowerShell script called InitDeviceClass that'll bring our wrapper into play.  You can see this function in the completed PowerShell script at the end of this post, it looks complicated, but in reality it only has two statements.  The first statement defines a string variable named $SourceCode which contains the entire source for our wrapper.  Just copy/paste the whole source from Visual Studio into the PowerShell ISE.  The second statement does all the work, so let's take a closer look at that.

Add-Type -TypeDefinition $SourceCode

Add-Type is a new cmdlet introduce with PowerShell 2.0 that lets you define a .NET Framework class in your Windows PowerShell session.  For a complete description check out the MSDN reference.  The -TypeDefinition parameter is where we tell Add-Type how to find the type definition that we want to add.  In this case, we're just passing it the entire C# source file, which it'll compile and make available to us.  If your C# has errors in it, Add-Type will return an error letting you know that there were compile-time errors with your code.

That's it.  The wrapper is now loaded and ready to use, so let's see how that works.

Step 4: Call the methods defined in your wrapper class from PowerShell

Our wrapper defines one public static method, which makes things pretty easy.  All we need to do is call our init function and then the wrapper is ready to use.  The syntax is exactly the same as my old [System.IO.File]::Exists() crutch.

And there you have it.  Win32, wrapped in .NET, then wrapped in PowerShell, ready to be added to your Troubleshooting Pack resolver script.  Here is the complete PowerShell script.  Enjoy!

-MB

"The troubleshooter made some changes to your system.  Try attempting the task you were trying to do before."

If you're building a diagnostic that is more like the maintenance troubleshooter that's task-driven rather than problem-driven and would like to change the messaging, you can.  Add the <Maintenance/> extension point to your troubleshooting pack and the messaging will become a bit more generic.  Here's a comparison of the two options.  Take a look at the maintenance package in %windir%\diagnostics\scheduled\maintenance\DiagPackage.diagpkg for a complete example.

-MB

Comparison.jpg

1.       A computer running Windows 7

2.       Basic understanding of PowerShell

3.       Windows 7 SDK

The first step is to install the tools that we’ll use to build your troubleshooting pack.  These tools are included in the Windows 7 SDK, which is available here.  If you’re only interested in building troubleshooting packs you don’t need to install the entire SDK, you only need to install the “Win32 Development Tools”

Now let’s get into the tool and start building a troubleshooting pack.  Launch the Windows Troubleshooting Pack Designer.

1.       Start

2.       All Programs

3.       Microsoft Windows SDK v7.0

4.       Tools

5.       Windows Troubleshooting Pack Designer

Remember, we’re building a game, which isn’t the most appropriate use of this technology, but whatever.  We’re going to build a simple question and answer game.  Select New from the Project menu to create the troubleshooting pack.  Call this pack “Guess” then click create.  Now we get to define what our troubleshooter will look like.  On this first screen we can see the project name, description, and privacy URL, all of which will be displayed on the first screen of the troubleshooter.  Add a description to your troubleshooter and enter in a URL for the privacy link (this can be any URL for now).

Next we need to add a “Root Cause”.  In a real troubleshooter the root cause is a specific problem that you’re trying to fix, like “service x is stopped”.  For our guessing game, we’ll make a root cause for when the player guesses incorrectly.  Click “Add New Root Cause”, enter the following values, and then click next.

• Root Cause ID: GuessIsWrong
• Root Cause Name: Oops!  You've guessed wrong!
• Root Cause Description: The answer you selected was incorrect.

The next screen will ask us a little bit more about this root cause.  Does the user need to be elevated to detect the problem?  Does the user need to answer any questions?  We don’t need elevation, but we do need the user to answer questions, so check Yes under Interactions.  Notice that when you select yes a new list of interactions appears.  We’ll define the questions for our game here.  Click the Add Interaction button. 

The Interaction Designer needs to know which type of question we want to ask.  We’re going to limit our game to single answers of a multiple choice question, so select the single response type.  Next you’ll need to define the specifics for this interaction.  Enter the following values.

• Interaction ID: Question_01
• Question or Prompt: In what year was Microsoft founded?
• Explanation: Please select an answer from the list of choices below.

Now we need to add some answers.  Scroll down to the Choice List, click Add Choice, and enter the details for each answer.  The title and description fields will be shown to the player; the value field will be used by our PowerShell script to determine which answer was selected.  Add the choices listed below, and then click OK.

Each root cause that you define needs a resolver.  This is the action that should be taken when the root cause is detected.  In our case, we want to educate the player if they choose the wrong answer.  Click Add Resolver and fill out the fields as follows.

• Resolver Name: Show the history of Microsoft
• Resolver Description: Display "The History of Microsoft" video series on Channel 9
• Prompt the User: Yes
• Elevation: No
• Interactions: No

Finally, we must define if the fix can be verified.  For the purposes of our game we won’t ask the player the same question again.  Click Define Verifier, select no under verifiable then click next. 

Now you’re ready to save and run your troubleshooting pack.  Click save, then select run from the build menu.  First you’ll be asked to install a test certificate for testing, click OK to continue.  If you skip this step your troubleshooting pack won’t work! 

At this point your troubleshooter doesn’t do much, but that’s about to change.  Notice that when you ran the troubleshooter it found the “Oops! You’ve guessed wrong!” problem.  Let’s go change this so that it’s based on the answer to our question.  Click on the Scripts node in the troubleshooting pack designer, then click edit troubleshooter script.  This will open the PowerShell editor and display your troubleshooting script.  You’ll notice that by default is just passes true to the update-diagrootcause cmdlet, which tells the troubleshooter if the problem was found. 

First thing we need to do is show the player the question and get the answer.  This is pretty simple; all we need to do is call the get-diaginput cmdlet, pass it the id of our question, and get the result.  This is what that looks like in PowerShell

#Ask the customer a question
$Answer = Get-DiagInput –id Question_01

The answer variable will contain the value, not the text, for the selected answer.  Next we need to determine if the answer is correct.  In this case, the correct answer is “1975”, which has a value of 1. This is the value that we entered for this item in the choice list.  Checking for the correct answer is now pretty simple; if the answer is 1 then they answered correctly, otherwise it’s incorrect.  Here is the completed PowerShell for our troubleshooter.  Notice that I’ve also changed $RootCauseDetected to set the problem (“Oops! You’ve guessed wrong!”) to be true only if the answer is incorrect. 

Save your PowerShell script, switch back to the troubleshooting pack designer, and hit run.  Now the player has a question to answer!  Run thru it a few times picking different answers to see how the rest of the experience changes. 

Now it’s time to set up our resolver.  Click on the scripts node again, then click edit resolver script.  By default, your resolver script is empty.  We want to display the “History of Microsoft” web page if they user answers incorrectly.  To do this, add the following line to your PowerShell script. 

explorer.exe “https://channel9.msdn.com/shows/History”

That’s it.  Save your script and run your troubleshooter.  Now when the player answers incorrectly they’ll be taken to the site.  Our game is complete!  This is a very simple example, but you’ve used most of the elements that you’d need to build a full-fledged troubleshooter.  You’ve asked the customer for input, evaluated their answer, and taken an action when the “problem” was detected.  We could flesh out this game a bit more by adding more questions, keeping score, loading questions from a file, etc.  All of this is possible within the windows troubleshooting pack framework.  You can even create your own text-based adventure game as a troubleshooting pack; maybe I’ll cover that in a later example…

It’s not the intended purpose of the platform, but it’s good for a laugh.  Enjoy!

-MB