Install Windbg

Windbg is the tool for the ASP.NET support engineer. It is free and it’s available at The learning curve is steep to say the least, but if you’re interested in finding out what is going on behind the scenes in your application, then Windbg is your new best friend. For information on how to configure windbg, please refer to the documentation. Pay special attention to the section concerning symbols.

There is an extension called SOS.dll that you will want to use. You’ll find it in the framework directory so for Framework 2.0 look in “C:\Windows\Microsoft.NET\Framework\v2.0.50727”. You might want to copy it into the same folder as windbg for easy access.
Get a memory dump

Windbg will allow you to either perform a post mortem analysis on a memory dump or to attach to a process during execution. I mainly deal with memory dumps, since it’s a lot easier to request a single file from a customer rather than access to their server. Maybe I’ll cover live debugging in another post, but for now we’ll just look at dump files.

If you’re running Windows Vista, then you can easily create a dump file from the task manager. Simply open up the “Processes”-tab, right-click the process you wish to dump and select “Create Dump File”.

For any other system or if you want to specify certain conditions I’d recommend using a script called adplus. It comes with the Windbg installation and is run from the command prompt. Adplus will take a number of arguments, but for basic operation there are two things you need to specify:

1. When to take the dump
2. The name or process ID of the process you wish to take a dump of

The dumps generated by adplus will be saved to a subfolder of the folder where you’ve installed windbg.

For example:
adplus -crash -pn w3wp.exe

This will generate a full memory dump right before any process named w3wp.exe terminates or recycles. This will also generate minidumps on all first chance exceptions.

adplus -crash -pn w3wp.exe -NoDumpOnFirst

Same as above, but without the minidumps.

adplus -hang -p 2960

This will immediately get a full dump of the process with ID 2960. Commonly used when the process has hung, or is generally unresponsive. Hence the name.

Advanced Adplus

If you’re trying to pin down the cause of a specific exception, then you can use a config file. This is a sample config file that will create a full memory dump once a System.Runtime.InteropServices.COMException occurs. Simply copy the code below into notepad and save it as MyConfig.cfg.


!load clr10\sos


!clr10\sos.cce System.Runtime.InteropServices.COMException 1; j ($t1 = 1) ‘.dump /ma /u c:\dumps\exceptiondump.dmp;gn’ ; ‘gn’

As you can see you can easily adjust the config so that it gets a dump on any other exception. The dump will be saved in c:\dumps, so you should also make sure that this folder exists. When you’re ready, run adplus with the following syntax:
adplus -c myconfig.cfg -pn w3wp.exe

Debugging through a Terminal Server session

If you don’t have direct access to the server you need to either attach noninvasively or schedule the command you wish to run. This can seem a bit complicated, but there’s a pretty good howto written in the knowledge base under the following article:

I followed the instructions in the article and they are pretty straight forward. However, there are a couple of caveats that are worth mentioning and hopefully might save you some time and agony:

* When running the command line “cscript adplus.vbs -crash -pn aspnet_wp.exe -o c:\crashdump” you might see a message regarding a missing environment variable _NT_SYMBOL_PATH.

To solve the problem you can add an environment variable and set it to the debugger symbol path (e.g.: C:\Symbols). You can add an environment variable by pressing the right button on my computer and choosing properties and then advanced/environment variables…

* To debug the process you will probably have to connect to your server remotely. If your server is running Windows 2000 and you are using a terminal services remote session, you can not debug a native process from another session. You can read Windows 2000 does not support cross-session debugging using a terminal server for more info. To solve this problem use the following trick. Although you can not debug the running process directly you can still make a snap shot of it and debug/examine the debug dump. The following command will take a snapshot of the asp net process:

“cscript adplus.vbs -hang -pn aspnet_wp.exe -o c:\crashdump”

Note the command line uses the –hang command line switch instead of the –crash.

* The article refers to using SOS extensions for debugging managed code. If you are running .Net 2.0 the following command “.load clr10\sos” will not work. Any command you try will give you the following descriptive message “Doesn’t work with 2.x”. To solve this problem use the “.loadby sos mscorwks” command instead. You can find more info about it here.