Click here to Skip to main content
Click here to Skip to main content
Technical Blog

Tagged as

Debugging Deeper through Reference Source

, 12 Apr 2014 CPOL
Rate this:
Please Sign up or sign in to vote.
A little over a month ago, the ASP.NET team announced several changes and updates to the .NET Reference Source and in this post we are going to discuss how to actually integrate it into Visual Studio so that you can step into the actual .NET Framework source when debugging your applications. What is

Debugging Deepr

A little over a month ago, the ASP.NET team announced several changes and updates to the .NET Reference Source and in this post we are going to discuss how to actually integrate it into Visual Studio so that you can step into the actual .NET Framework source when debugging your applications.

What is Reference Source again?

Reference Source, if you are unfamiliar with it, was a project that Scott Guthrie and his team started back in 2007 in hopes of releasing the .NET Framework source to allow developers to easily reference it (without all kinds of decompilation and mischief) to see what was really going on under the hood. Shortly after that release, the team made a few changes that would allow developers to actually step through the source code which was a major step in a very cool direction.

One of the major difficulties with managing something that is constantly evolving like the .NET Framework is purely the fact that it is “constantly evolving”. Updating documentation usually takes time and with a project of this magnitude, it could simply be something that is “left over until the end” or simply doesn’t get done :

Reference Source circa 2007.

Reference Source circa 2007 via Scott Guthrie

Reference Source Meets Roslyn.

As part of this year’s announcement regarding Reference Source, it was mentioned that it would be joining forces with Microsoft’s latest development wonder, Roslyn.

Roslyn is a managed compiler-as-a-service that has really flipped the script in the .NET world recently. It provides all kinds of wonderful features that were simply not possible in previous years and has already been used not only by Microsoft but in many other arenas such as .NETFiddle, Bing Code Search, Semantic Merge and more. Roslyn was used to help generate a semantic index of the entire .NET Framework source to allow it to be searched through with the greatest of ease.

Currently, .NET 4.5.1 is indexed and readily available on the Reference Source site and the ASP.NET team announced a commitment to keep things updated with each upcoming release as they occur to prevent any stagnation that may have plagued the previous versions of the tool. So you can be relatively sure that whenever you are accessing the latest version of the Reference Source that it should be the latest and greatest. The improvements were not limited to just performance either.

The UI received a very stylish overhaul as well and yield some of the nicest looking documentation that you’ll come across :

The New and Improved Reference Source

The New and Improved Reference Source

Another undocumented feature is the tiny snippets of entertaining comments that you can find scattered throughout the source as well :

An example of one of the many entertaining comments throughout the source.

An example of one of the many entertaining comments throughout the source.

Putting it to Good Use.

Let’s actually put the Reference Source to use along with Visual Studio 2013 and use it to debug an application by not only stepping through our own code, but into the source of the .NET Framework as well.

To get started, there are a few changes we need to make within Visual Studio that will allow us to target the Reference Source (which will primarily consist of enabling and disabling a bunch of properties in the Options menu).

Open up Visual Studio and navigate on over to the options menu (Tools > Options > Debugging > General) as seen below :

You'll need to enable and disable the following options within the Debugging Options in Visual Studio

You’ll need to enable and disable the following options within the Debugging Options in Visual Studio

and then you are going to disable the following options :

  • Just My Code
  • Step over Properties and Operators (Managed Only)
  • Require Source Files to Exactly Match the Original Version

and enable these ones :

  • Enable .NET Framework Source Stepping
  • Enable Source Server Source

After making the changes, your options menu should look like this :

This is what your Debugging Options should look like prior to stepping through Reference Source

This is what your Debugging Options should look like prior to stepping through Reference Source

Then, you’ll need to make sure that when debugging that you are targeting the actual Visual Studio Reference Source. You can do this by visiting the Symbols area under options (Tools > Options > Debugging > Symbols) :

You'll need to access the Symbols area in order to use Reference Source when debugging

You’ll need to access the Symbols area in order to use Reference Source when debugging

From here, you’ll want to target the Reference Source symbols available at http://referencesource.microsoft.com/symbols. You’ll need to click the Add Symbols option within the Symbols area and add the previously mentioned URL :

Click the Folder icon and add the appropriate symbols reference for Reference Source

Click the Folder icon and add the appropriate symbols reference for Reference Source

What I have found to be a safer and more reliable approach however, is to simply download the source and reference it locally from the following location :

http://referencesource.microsoft.com/DotNetReferenceSource.zip

After making those changes, you’ll need to ensure that the project that you are going to be debugging is targeting .NET 4.5.1. Debugging through Reference Source is going to currently be limited to 4.5.1 and above since those are the only actual versions of the .NET source that have been indexed so far.

Looking Under the Hood.

Now that we have configured everything, let’s make a really simple program to demonstrate traveling through the source.

// Generate a collection of values (1-100)
var numbers = Enumerable.Range(1, 100);
// Order them randomly
numbers = numbers.OrderBy(n => Guid.NewGuid());
// Store these values in an array
var numberArray = numbers.ToArray();
// Sort the array
Array.Sort(numberArray);

Using the simple program above, we will create a collection of numbers, randomly order them, store them in an array and then finally sort them using a variety of methods.

Let’s place a breakpoint on the first line and run the program.

When you hit your first breakpoint, right-click on the method (in this case System.Linq.Enumerable.Range) and you should see an option within the context menu called “Step Into Specific” which will allow you to send the debugger into the .NET source for that particular method as seen below :

You can use the "Step into Specific > (Your Method)" option to debug through the .NET source.

You can use the “Step into Specific > (Your Method)” option to debug through the .NET source.

After selecting the method to step into through “Step into Specific”, you’ll see that the debugger jumps into the related .NET source and you can step through the method as you would expect within any other .NET application being debugged :

After using the "Step into Specific" option, you'll be presented with the source for your specific function, which you can debug as expected.

After using the “Step into Specific” option, you’ll be presented with the source for your specific function, which you can debug as expected.

And that’s basically all you need to know about using Reference Source within Visual Studio to debug your applications. You should be able to jump into any of the assemblies that are currently supported within Reference Source without any issue.

Considerations

A few other considerations if you are having trouble :

  • Debugging through Reference Source currently ONLY works for full versions of Visual Studio 2013 (sorry no Express versions). I’ve spoken with several members of the Visual Studio team and they are looking into possibly removing this restriction in the future.
  • Ensure that the assembly that you are attempting to step into is one of the available assemblies for debugging mentioned here.

If you still continue to encounter any errors or something isn’t working that you believe should – contact the Reference Source Feedback team via the “Feedback” link on the Reference Source page.


Filed under: CodeProject, Development

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Rion Williams
Software Developer (Senior)
United States United States
An experienced Software Developer and Graphic Designer with an extensive knowledge of object-oriented programming, software architecture, design methodologies and database design principles. Specializing in Microsoft Technologies and focused on leveraging a strong technical background and a creative skill-set to create meaningful and successful applications.
 
Well versed in all aspects of the software development life-cycle and passionate about embracing emerging development technologies and standards, building intuitive interfaces and providing clean, maintainable solutions for even the most complex of problems.
Follow on   Twitter

Comments and Discussions

 
-- There are no messages in this forum --
| Advertise | Privacy | Terms of Use | Mobile
Web01 | 2.8.1411023.1 | Last Updated 12 Apr 2014
Article Copyright 2014 by Rion Williams
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid