Debugging into the .NET Framework Source

As promised, Microsoft has made the source for the .NET Framework available for debugging purposes. You’ll need to be running Visual Studio 2008 and install this QFE (aka patch). Full instructions for how to enable .NET Framework source debugging can be found on Shawn Burke’s blog here. You can also read Scott Guthrie’s announcement here.

As luck would have it, I couldn’t get this working initially. There was no "Load Symbols" in the right-click menu of the call stack. ("Load Symbols" should appear right above "Symbol Load Information…")

image

Double-clicking in my call stack on any frames in the .NET Framework:

image

resulted in:

image 

After some quick investigation and reading through Shawn’s troubleshooting section at the bottom of his post, I realized that the _NT_SYMBOL_PATH environment variable was overriding the settings in Visual Studio. (I had set up _NT_SYMBOL_PATH to the Microsoft Symbol Server for WinDbg.) The problem is that the symbols provided by the Microsoft Symbol Server have their source information stripped out.

To solve this problem, you have two options.

  1. Delete the environment variable and just set the symbol paths in Visual Studio and WinDbg independently as noted in Shawn’s blog post above.
  2. Add the Reference Source Symbol Server to _NT_SYMBOL_PATH. (This has the advantage that the setting is shared by all debugging tools, including Visual Studio and WinDbg.)

Regardless of which option you choose, first close all instances of Visual Studio 2008 and delete all the files in your local symbol cache. Visual Studio has no way of knowing which version of the symbols you have. So if you already have System.Web.pdb downloaded from the Microsoft Symbol Server – the PDB file without source information – you won’t be able to debug into System.Web.

To add/modify the environment variable:

  1. Right-click Computer… Properties…
  2. On Vista, click Advanced System Settings…
  3. Click on the Advanced tab, then Environment Variables…
  4. Click New… under System Environment Variables (or Edit… if _NT_SYMBOL_PATH is already defined).
    • Variable name: _NT_SYMBOL_PATH
    • Variable Value: SRV*c:\dev\symbols*http://referencesource.microsoft.com/symbols;SRV*c:\dev\symbols*http://msdl.microsoft.com/download/symbols
  5. Click OK three times.

Maybe I’m just dense, but it took me awhile to figure out the syntax for _NT_SYMBOL_PATH. Note that you have to separate symbol servers via a semi-colon. Specifying SRV*LocalCache*Server1*Server2 fails miserably. Symbols don’t download and no errors are shown. The four-part syntax is valid, but meant for caching symbols on your network for all developers to share. Local cache is on each developer’s box, Server1 is a fileshare on your network with read-write access for all developers, and Server2 is the actual public symbol server. If you specify a public symbol server as Server1 in the four-part format, symbol loading just fails silently. Use the semi-colon separated syntax noted above to specify multiple public symbol servers and everything works as expected.

The local symbol cache can be the same for all public symbol servers. It can be anywhere that you have read/write access, such as c:\symbols, c:\users\james\symbols, or – my preferred location – c:\dev\symbols.

You should be sure that the Reference Source Symbol Server is before the Microsoft Symbol Server. The order of symbol servers is the order of search. If your debugger doesn’t find the correct PDB file in the local symbol cache, it will check the first symbol server. If the first symbol server doesn’t have the appropriate PDB file, it will proceed to the second. So if you have the Microsoft Symbol Server first, you’ll be downloading the PDB files without source information.

Which brings me to my last point. Right now, source has been released for:

  • .NET Base Class Libraries (including System, System.CodeDom, System.Collections, System.ComponentModel, System.Diagnostics, System.Drawing, System.Globalization, System.IO, System.Net, System.Reflection, System.Runtime, System.Security, System.Text, System.Threading, etc.)
  • ASP.NET (System.Web, System.Web.Extensions)
  • Windows Forms (System.Windows.Forms)
  • Windows Presentation Foundation (System.Windows)
  • ADO.NET and XML (System.Data and System.Xml)

LINQ, WCF, Workflow, and others will be following in the coming months, according to Scott Guthrie. So if I debug WCF today, I’ll download symbols from the Microsoft Symbol Server without source information since the Reference Source Symbol Server won’t have the PDB files. When the PDB files are released, I won’t be able to debug the source until I delete the old PDB files without source information and force a re-download. You can do this by deleting the appropriate folder in your local symbol cache – in this case, the c:\dev\symbols\System.ServiceModel.pdb folder – or you can just delete the entire contents of your local symbol cache and re-download everything. If you’re not able to view source on something that you know is available, the easiest solution is to just clear out your local cache and let Visual Studio download the symbols again from the correct location. Downloading symbols over a broadband connection doesn’t take that long and is a lot faster than trying to troubleshoot which PDB files are causing you problems.

Happy Debugging!!!

About James Kovacs

James Kovacs is a Technical Evangelist for JetBrains. He is passionate in sharing his knowledge about OO, SOLID, TDD/BDD, testing, object-relational mapping, dependency injection, refactoring, continuous integration, and related techniques. He blogs on CodeBetter.com as well as his own blog, is a technical contributor for Pluralsight, writes articles for MSDN Magazine and CoDe Magazine, and is a frequent speaker at conferences and user groups. He is the creator of psake, a PowerShell-based build automation tool, intended to save developers from XML Hell. James is the Ruby Track Chair for DevTeach, one of Canada’s largest independent developer conferences. He received his Bachelors degree from the University of Toronto and his Masters degree from Harvard University.
This entry was posted in .NET, featured. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • http://www.jameskovacs.com james.kovacs

    @Focus – The only supported configuration for .NET Framework Source Debugging is with Visual Studio 2008. You can reportedly get it to work in VS2005 and Express Editions by downloading all the symbols/source at once using NetMassDownloader:

    http://www.codeproject.com/KB/dotnet/netmassdownloader.aspx

  • Focus

    I’m trying to debug, but i have some problems. I have set up the enviroment variable _NT_SYMBOL_PATH, but it doesn’t works.

    When I try to debug for example textBox1.Text = “Debug”; I load the symbols for System.WindowsForm, anb I Debug but a message appears saying that “The debugger must execute this untrustet command to obtain source code from source server” , button “Run” and “Don’t runt” and the command is emtpy.

    When I click run, a File dialog appears asking form Form.cs in f:\RedBits\ndp\fx\src\WinForms\Managed\System\WinForms\TextBox.cs

    I’m trying to debut with vs 2005

  • http://www.jameskovacs.com james.kovacs

    @Matt – Yes, I’m debugging into .NET Framework source right now. One thing I wasn’t clear on in my post… Even if you have _NT_SYMBOL_PATH set, you still need to set the VS Tools… Options… Debugging… Symbols… to the symbol server. You only need:

    http://referencesource.microsoft.com/symbols

    and the cache directory matching the one set for _NT_SYMBOL_PATH. This allows VS 2008 to find the symbols.

    The original problem was that _NT_SYMBOL_PATH was overriding the download behaviour and not allowing symbols with source to be downloaded.

  • http://sticklebackplastic.com Matt Ellis

    Hi James. Have you got the source server stuff working in VS by using the environment variable?

    I’ve set it up, and it almost works, but it always tries to load the source files from the local path (“f:\ReBits\ndp\clr\src\…”) instead of from the http path.

    Have you got it working fully?

    Cheers
    Matt

  • http://blogs.msdn.com/sburke Shawn Burke

    Great Post James! I’ll send people here if they are in the _NT_SYMBOL_PATH camp…