.NET Reflector Pro: Debugging the .NET Framework Source Code

The other day, I ran into a situation (see the attached project and here for more info) where I wanted to debug the .NET Framework in order to see how something was working.

Unfortunately, Visual Studio’s native support (see Scott Guthrie’s blog post or Shawn Burke’s blog post) for doing so was failing me. I was eventually able to get that working for .NET 4.0 but not .NET 3.5 SP1 (see this forum thread), but in the meantime … I had to turn to other methods.

So, what is one to do when this happens? Is all lost? Not at all, for you can use .NET Reflector Pro to do the same thing.

.NET Reflector is a very popular .NET utility created by a Microsoft employee, Lutz Roeder. It allows you to explore and analyze .NET managed assemblies. This utility can also be extended by way of add-ins and there is a whole bunch of them out there.

A while ago, Lutz Roeder, decided to let Red Gate take the reins, and they then went ahead and added the ability to allow a user to debug into third-party code and assemblies by way of a Visual Studio add-in.

And that is what I’m going to show you how to do, step-by-step.

Install .NET Reflector Pro

The first thing that you need to do, obviously, is to download and install .NET Reflector, if you haven’t already. There is a download link here.

It comes down as a zip file, so simply extract the contents to a convenient location. Launch it and then select Tools->Integration Options. Here is the dialog that comes up.

This dialog allows you to easily install the .NET Reflector add-in … into Visual Studio. Choose the versions that you want and click OK.

Tell Visual Studio to Disable Optimizations

The next step is very important. If you forget it, you will be frustrated once you get to actually debugging the source code … because all the variables will be optimized away and Visual Studio will also step through the code in odd ways.

So, go to my earlier blog post and follow its instructions. (Also, don’t forget, if you are debugging a Visual Studio 2010 application, to make sure you update the path to devenv.exe … in the .cmd file you create in this step.)

Choose the Assemblies to Debug

Next, launch Visual Studio with the .cmd file from the previous step and load up the project that you want to debug. Go to the .NET Reflector menu and select ‘Choose Assemblies to Debug…’

If you don’t have your options set correctly, the following dialog will come up. Click ‘Turn off “Enable Just My Code”’ to continue.

Now, choose which assemblies that you wish to debug into … via the following dialog.

In my case, I want to debug the ContentPresenter.EnsureTemplate method and the ContentPresenter class lives in PresentationFramework.dll. How do I know this? Well, through .NET Reflector, of course.

Activate .NET Reflector Pro

Once you click OK to the above dialog, you may get prompted with the following dialog.

This, unfortunately, brings up an annoying issue. Even though Red Gate has kindly provided a 14-day trial to use the Pro features of the tool … your trial starts when you install the software and not when try to use the debugging feature for first time.

That is, for me, I was never able to take advantage of the trial period as I had long had the software installed (it is always one of the first pieces of software I put on a newly paved development machine).

So, if you are in this situation, go buy a license and then Activate it here.

Let .NET Reflector Decompile the Assemblies

5. At this point, .NET Reflector Pro is disassembling the assemblies that you have chosen and also reassembling them so that they can generate .pdb files. This process takes quite a bit of time and so they also stuff the output into the ‘Debug Store’ so that you don’t have to do this every time.

If you’ve been around the .NET world for a bit, you’ll notice the similarities in the above step to what you had to do manually in this CodeProject article. And, if you recall, what you ended up debugging … was IL, not C# or VB.

Eventually, everything will succeed.

Verify Your Tools->Options Debugging Settings

At this point, bring up the Tools->Options dialog and go to the Debugging/General tab. Everything should be fine, but as a point of education … and to verify that everything is okay … make sure that all settings pointed to by the red arrows are set as shown.

.NET Reflector cleared the first one (‘Enable Just My Code’) for you … but make sure it is unchecked.

Also, make sure that ‘Enable .NET Framework source stepping’ and ‘Enable source server support’ are unchecked. These options are checked when you are using Visual Studio’s native support to debug into the .NET Framework (mentioned above) … but we don’t want them checked now … so that there is no cause for confusion.

Finally, the ‘Require source files to exactly match the original version’ is not strictly necessary. However, I believe I have had issues in the past if this was checked. If you leave it checked, just keep it in mind, so if things aren’t working you can then try unchecking it.

Next, check out the Debugging/Symbols tab. Below, you can see where .NET Reflector has installed the .pdb files. Make sure those locations are checked … and make sure that everything else in that list is unchecked … especially ‘Microsoft Symbol Servers’

And, very importantly, make sure you have a clean symbol cache … by clicking the ‘Empty Symbol Cache’ button. Why is this important? Well, it ensures that all the .pdb files will be coming fresh from Reflector … and won’t be a stale .pdb from a previous effort at trying to use the native Visual Studio support.

What is the Symbol Cache? Well, the Symbol Cache is where the .pdbs are copied to … so that you don’t have to keep downloading them from the Microsoft Symbol Servers … obviously an important option when using the native Visual Studio support … but not super important when dealing with .NET Reflector. However, I believe Reflector’s .pdb files still get copied to the Symbol Cache.

Debug the .NET Framework (Call Stack Approach)

Now, you need to figure out how to set a breakpoint so that you can break into the application and debug the .NET Framework. The first mechanism is just to set a breakpoint on a local (non-framework) method that you know will cause the class of interest to be on the stack. Then you can double click the stack frame and set another breakpoint as necessary.

For example, let us say that I want to debug System.Windows.Application.DoStartup. I know that the Application class will probably be on the stack if I put a breakpoint in the InitializeComponent method of my MainWindow. So, that’s exactly where I put it.

Now, I click Debug->Start Debugging (F5) and hopefully I will hit my breakpoint. Sure enough:

One thing to note here is that gray text indicates that a .pdb has not been loaded for that assembly while black text indicates that a .pdb has been loaded. That is, in the above example, only PresentationFramework has an loaded .pdb.

And, look! Application.DoStartup is on the stack. Double click that stack frame to bring you to the code.

At this point, you can debug as normal. You can step, watch variables, and more. In the above screen shot, you can see that I set a new breakpoint at the start of the method to be hit when I restart the debugging session. Restarting the application, shows that I can verify that MainWindow.xaml is my StartupUri.

Debug the .NET Framework (Method Breakpoint Approach)

Unfortunately, the above call stack approach to debugging the .NET Framework will only get you so far. Another method I have used in the past is to simply set a breakpoint on a method name. How to do this is not very obvious, though.

The trick is to set a breakpoint via the New->Break at Function menu item in the Breakpoints debugging window.

The New Breakpoint dialog comes up. Simply, and carefully, type the name of the method, prefixed by its Class name, like so:

It will complain, but just click OK.

At this point, just hit F5 (Debugging->Start Debugging) and do what you need to do to hit the breakpoint. And, wa la, here I’ve hit my breakpoint:

The real question that prompted all of this desire to debug the .NET Framework was to see whether the DataContext was getting set or cleared inside of ContentPresenter. And so, I set the following breakpoints and step to my hearts content.

Summary

Sometimes, you are up against the wall. You are trying to determine if the .NET Framework has a bug in it … or you’re just trying to get a better grasp about what is really going on in that big black box.

And, while debugging the .NET Framework is best done natively inside of Visual Studio (it’s easier and you can see comments in the source code), it doesn’t always seem to work. Sometimes the assembly you are trying to debug is not supported and at other times the symbol servers don’t seem to be up to date with the released bits.

However, .NET Reflector Pro can come to your rescue in these situations. It can also debug any third-party assembly, regardless of whether it’s Microsoft’s or not.

Good hunting … I hope this helps someone out! Leave a comment if it does!