When Microsoft announced the release of the .NET Framework source under the Microsoft Reference License (MS-RL) it has been perceived with extremely positive feedback by developers around the globe. With Visual Studio 2008 RTM available for download for MSDN subscribers it is anticipated that instructions about enabling this new feature will be publicly available before the end of this year.
Thanks to Shawn Burke and Scott Guthrie, both from the Developer Division at Microsoft I've received prerelease instructions and set up my .NET Framework source code debugging today. Here are detailed instructions, most of them taken from a detailed email Shawn sent to me yesterday.
First of all you do need Visual Studio 2008. The RTM version has been made available for download to MSDN subscribers last month and trial editions are available, too.
Step 1:
Start Visual Studio 2008 and select Tools -> Options -> Debugging.
Step 2:
On the “General” Tab
a. Uncheck “Enable Just My Code (Managed only)”:
b. Check “Enable source server support”.
Step 3:
On the “Symbols” tab:
a. Click the “New” icon and enter the URL to the Microsoft symbol servers:
b. Check “Search the above locations only when symbols are loaded manually”.
c. Enter a path in the textbox in which to cache symbols. Make sure this is somewhere that your user account has permissions to write to.
d. Hit OK.
Step 4:
Launch your debugging project and hit a breakpoint in your code.
Step 5:
When you hit your breakpoint, open the call stack (Debug -> Windows -> Call Stack), then right-click on a frame for the assembly you would like to load symbols for, for example System.Web.dll, then choose “Load Symbols”. If you haven’t already downloaded the symbol files (these are cached permanently on your machine in the directory specified above after downloading), the symbols will download and be loaded by the debugger – Visual Studio may not be responsive during this time, so please be patient.
Step 6:
Now you can load source for the call frame by simply double clicking the call frame, or by any other action that would cause a file to load such as stepping in (F11) or out of a call. Some source files are very large (up to 800K) so please be patient while they download. On most connections, the download should take a maximum of 20 seconds for the very large files and ~5 seconds for most files.
Step 7:
If it is your first time accessing the source, you will be shown a EULA that you must accept to access the source repository. Note that you may see two EULAs – one for source, one for symbols.
That's it! On my machine Shawn's detailed instructions worked like a charm and I've been able to step into e.g. Windows.Forms.dll as if its source would belong to my project. Downloading time was absolutely fine for me.
Here are some tips and tricks and known issues Shawn shared with me:
KNOWN ISSUES/FAQ
1. WHY IS SOURCE LOADING SO SLOW? The primary issue that we are trying to address/improve is performance of downloading the source files. We are working on several improvements here.
Source files should be cached for the duration of the VS 2008 instance, and there is an issue which causes them to be unnecessarily re-loaded each time they are accessed. A hot-fix is currently being prepared to address this (hopefully available this week). We are also working on other mechanisms to help improve this, so we definitely understand this is an issue, so stay tuned for improvements here.
2. HOW DO I SET BREAKPOINTS IN THE FRAMEWORK SOURCE? Setting breakpoints in the breakpoint engine within Visual Studio expects the source files to exactly match the original source in order to be set. The source files available through the .NET Framework Reference Source have the same code as the original files but have some small changes like having a standard copyright banner included at the end. If you would like to set breakpoints in the .NET Framework code, there are two ways to address this:
a. Set the breakpoint, then right click the red-circle and choose “Location…”, then choose “Allow source file to be different from the original location”
b. You can set this globally by going to Tools -> Options -> Debugging -> General, and unchecking “Require source files to exactly match the original version”. Remember that this will affect all of your projects and debugging, though in most cases it won’t be an issue.
3. WHY DON’T DEBUGGING FEATURES LIKE “GO TO DEFINITION” WORK? Browse database information is separate from symbol (PDB) information within the debugger, so that information is maintained by the project system when a project is compiled and is not present within the symbol files. So, unfortunately, that ability is not available here.
4. WHY ARE SOME MEMBER OR LOCAL VARIABLES UNAVAILABLE? The .NET Framework bits that you have installed on your machine are “retail” bits, which means they are optimized for size and performance. Part of this optimization process removes certain information from the process when it is no longer needed. Debugging retail assemblies reflects this. However, most debugging information is still present in the session, and setting breakpoints earlier in a function often allows it to be visible. Another aspect of retail builds is that some small methods may be “inlined” which means you will not be able to step into them or set breakpoints in them. But for the most part you can step and debug as normal.
5. WHY DON’T I GET 64-BIT SYMBOLS? Symbols for 64-bit will work, but they haven’t yet been deployed to the servers. That should happen early this week. Only 32-bit symbols are currently available.
WHAT SOURCE IS CURRENTLY AVAILABLE
Source and symbols are currently available for the following assemblies as they shipped with the .NET 3.5 release:
· Mscorlib.dll
· System.DLL
· System.Data.DLL
· System.Drawing.DLL
· System.Web.DLL
· System.Web.Extensions.DLL
· System.XML.DLL
· WPF (UIAutomation*.dll, System.Windows.DLL, System.Printing.DLL, System.Speech.DLL, WindowsBase.DLL, WindowsFormsIntegration.DLL, Presentation*.dll, some others)
· Microsoft.VisualBasic.DLL
TIPS & TRICKS
· To get all of the symbols for the project you’re running downloaded at once, go into your Tools -> Options -> Debugging -> Symbols configuration and uncheck “Search the above locations when symbols are loaded manually” checkbox. Then hit OK (which may cause symbols to load immediately), then launch your debugging project. This will download all of the needed symbols and cache them on your machine, and since symbols (often over 50 MB total) are large it could take a while, so let Visual Studio sit while it finishes the download. After that’s complete, go back to Tools -> Options -> Debugging -> Symbols and check the “Search the above locations…” checkbox and hit OK. This is necessary because without it, at the start of each debugging session, the debugger will check the server for all of the symbols it failed to load. This will degrade the performance of your debugging session.
· An alternate way to do this is to run your project uncheck the box next to the URL after you have gotten all the symbols you need. You will need to check it again to download any additional symbols that may be added to the system in the future.
· Symbols are downloaded on-demand. So in all cases, only the symbols for the assemblies loaded by your project in the debugging session. So, if your project is a Web project, System.Windows.Forms will not download. Likewise, if your project references an assembly but it isn’t loaded at project startup, the symbols for that assembly won’t be downloaded until process loads the assembly.
Lat but not least, here is a screenshot of my debugging session inside Forms.cs:
Pretty amazing stuff!