How to Configure Visual Studio to Use SourceLink to Step into NuGet Package Source

Step-through debugging third party NuGet packages has never been easier.

I love SourceLink - it’s fast becoming a standard practice to include SourceLink support in all open source NuGet packages in order to make them easier to debug. We’ve included SourceLink support in Akka.NET and some of our other projects for some time now.

However, I’m embarrassed to admit that I’ve never been able to remember how to get this to work properly each time I switch machines or projects. So, I decided to document how to do it.

Step 0 - Verify That Your Third Party NuGet Packages Actually Support SourceLink

Before you go through the trouble of configuring Visual Studio to support SourceLink you’ll want to make sure that the third party package you’re trying to debug actually supports it.

The official Microsoft documentation on SourceLink has some guidance for how to do this, but odds are high that popular NuGet packages (i.e. ASP.NET, Newtonsoft.Json, Automapper, etc) already support it.

Step 1 - Configure Visual Studio to Support NuGet.org Symbol Sources

For reference, I’m using Visual Studio 2019 with .NET Core 3.0 for most of my day to day work. By default NuGet.org symbol sources aren’t enabled. In order for SourceLink to work properly Visual Studio needs to be able to download these sources, so we have to set this up first.

In Visual Studio, go to Tools –> Options –> Debugging –> Symbols:

Make sure the ‘NuGet.org Symbol Server’ option is checked.

Step 2 - Disable “Just My Code” in Visual Studio

Next, we need to go to the Tools –> Options –> Debugging –> General settings window and disable the “Just My Code” option:

Step 3 - Enable Source Server and Source Link Support in Visual Studio

By default SourceLink support is already enabled in Visual Studio, but source server support is not.

Again, go to the Tools –> Options –> Debugging –> General settings window and make the following changes:

N.B. If you use Github for Windows / Github for Mac, which both use the Git Credential Manager under the covers, checking the “Fallback to Git Credential Manager” will also allow you to use SourceLink for private repositories. However, since it’s unlikely that source code from a private repository is going to make it onto a public NuGet server or symbol server, so you will need another way to distribute the .PDB symbol files SourceLink requires. See “Alternative PDB Distribution” from the SourceLink documentation for some ideas on how to do this.

That should do it. Now we can take it for a spin.

Step 4 - Step into Third Party Code

So I have the following small program:

using System;
using FluentAssertions;
using Hocon;
using Newtonsoft.Json;

namespace SerializationDebug
{
    class Program
    {
        static void Main(string[] args)
        {
            var hocon1 = @"
                    foo{
                      bar.biz = 12
                      baz = ""quoted""
                    }";

            ShouldSerializeHocon(hocon1, string.Empty, string.Empty);
        }

        public static void ShouldSerializeHocon(string hocon, string fallback1, string fallback2)
        {
            var hocon1 = ConfigurationFactory.ParseString(hocon);
            var fb1 = string.IsNullOrEmpty(fallback1) ? Config.Empty : ConfigurationFactory.ParseString(fallback1);
            var fb2 = string.IsNullOrEmpty(fallback1) ? Config.Empty : ConfigurationFactory.ParseString(fallback2);

            var final = hocon1.WithFallback(fb1).WithFallback(fb2);

            VerifySerialization(final);
        }

        public static void VerifySerialization(Config config)
        {
        	// set breakpoint here
            var serialized = JsonConvert.SerializeObject(config);
            var deserialized = (Config)JsonConvert.DeserializeObject(serialized);
            config.DumpConfig().Should().Be(deserialized.DumpConfig());
        }
    }
}

I’m going to set a breakpoint at the line where we call Newtonsoft.Json.JsonConvert.SerializeObject, since in this case I’m trying to debug an issue with circular references in my code. When the debugger hits that line, make sure you press F11 or use the Step Into functionality to download the Newtonsoft.Json source code via SourceLink and step through it.

You’ll be prompted to download the source from Github and after you click “Accept” you’ll be able to view the source code for that specific version of your package.

And that should about do it. Good hunting!

Appendix: What if we don’t use Github for our private packages?

SourceLink has support for multiple code repository providers, including:

• Azure Repos / DevOps;
• GitLab;
• BitBucket; and
• Github, of course.

Thus, if you’re using a non-Github platform for developing a NuGet package you’ll want to make sure you reference the correct platform-specific flavor of the Microsoft.SourceLink package. You can read more about that here.

Discussion, links, and tweets

I'm the CTO and founder of Petabridge, where I'm making distributed programming for .NET developers easy by working on Akka.NET, Phobos, and more..

Tweet Follow @Aaronontheweb