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 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
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.
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
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
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
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
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.
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.
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.
rionscode 