Improved .NET Debugging Experience with Source Link

Source Link is a Microsoft technology that lets .NET developers debug the source code of NuGet packages referenced by their applications. I underlined source code because at debugging time the user doesn’t just get C# code decompiled from the IL code within referenced assemblies. Instead the developer debugs the original C# source code used to build the libraries, with original comments and formatting available.

Source Link is language, IDE and source-control agnostic. Source Link can be used from debugging sessions done through Visual Studio, VS Code or Rider IDE.

Debugging with Source Link in Visual Studio

The Newtonsoft.Json package supports Source Link. It means that when debugging the program below, one can step into the SerializeObject() method original source code.

Prior doing so a few settings must be setup in Visual Studio:

• Enable: Tools > Options > Debugging > Symbols > NuGet.org Symbol Server

• In Tools > Options > Debugging > General 
  • Disable: Enable Just My Code
  • Enable: Enable source server support  and  Enable Source Link support

Then start debugging the program (F5). Before starting the debugging session, it takes a few seconds to load symbols for packages referenced:

You can now Step-Into Newtonsoft original sources:

The file JsonSerializer.cs has been downloaded from GitHub and stored in the folder C:\Users\usr\AppData\Local\SourceServer\634989e5314d385c82c8a3269e286aacd49e4527b9c315d6bd38afcf4ee504e3\Src\Newtonsoft.Json.

How Source Link works?

If you download the Newtonsoft.Json package from NuGet and unzip its content, you’ll notice a generated file in it named Newtonsoft.Json.nuspec. This file contains a <repository> tag that points to both the location and commit hash for these bits:

In this scenario the package zipped doesn’t contain any PDB file. At debug time, this location and commit hash are used to fetch the source files and the PDB files from GitHub that are then stored locally in a \Temp\SymbolCache directory.

Enabling Source Link for your own Packages

Enabling Source Link for your own packages makes the life of the developers that use it much easier.

At the minimum a <PublishRepositoryUrlsproj> tag and a reference to a source link package must be added to your .csproj project file.

If you use GitLab or Bitbucket you could instead reference the Microsoft.SourceLink.GitLab or Microsoft.SourceLink.Bitbucket.Git package.

Embedding the PDB files

Some optional tags let’s embed the PDB files inside the main .nupkg package or in a side package with extension .snupkg. The first option is not recommended as it increases the size of the main package and thus increases the restore time, even for scenarios where symbols are not required.

NuGet.org hosts its own symbols server repository that works with .snupkg symbol side packages. In the first section of the present article, when we checked Tools > Options > Debugging > Symbols > NuGet.org Symbol Server we told Visual Studio to fetch symbol from the NuGet.org symbols server repository.

Embedding sources in the PDB file

Finally you can decide to optionally embed source files within the PDB files with these options:

Conclusion

With Source Link, the debugging process becomes smoother, more intuitive, and insightful, leading to accelerated development cycles With its seamless integration into the NuGet ecosystem, Source Link empowers developers to delve deep into the inner workings of their references, enabling them to troubleshoot and resolve issues with unprecedented efficiency.

Patrick Smacchia

Website

My dad being an early programmer in the 70's, I have been fortunate to switch from playing with Lego, to program my own micro-games, when I was still a kid. Since then I never stop programming.

I graduated in Mathematics and Software engineering. After a decade of C++ programming and consultancy, I got interested in the brand new .NET platform in 2002. I had the chance to write the best-seller book (in French) on .NET and C#, published by O'Reilly and also did manage some academic and professional courses on the platform and C#.

Over my consulting years I built an expertise about the architecture, the evolution and the maintenance challenges of large & complex real-world applications. It seemed like the spaghetti & entangled monolithic legacy concerned every sufficiently large team. As a consequence, I got interested in static code analysis and started the project NDepend in 2004.

Nowadays NDepend is a full-fledged Independent Software Vendor (ISV). With more than 12.000 client companies, including many of the Fortune 500 ones, NDepend offers deeper insight and full control on their application to a wide range of professional users around the world.

I live with my wife and our twin kids Léna and Paul in the beautiful island of Mauritius in the Indian Ocean.