The new and easy way to debug through NuGet packages with the Source Link

If you're using your own NuGet packages or consuming 3rd party ones, then you've probably faced the pain of stepping (or rather not stepping) through it's source code.

Forget the symbol and source servers, there's a new and friendlier kid on the block: Source Link. Formerly you had to upload your symbol (PDB) and source files to different locations and use several switches during the build. Even that didn't guarantee you success, downloading source files often failed miserably.

Source Link is here to ease your pain, it is a developer productivity feature that allows unique information about an assembly's original source code to be embedded in its PDB during compilation.

Setting it up the Source Link is quite easy, firstly lets enable Source Link support in Visual Studio: Options > Debugging > General > Enable Source Link support. Then add the following reference to your project:

    <PackageReference Include="SourceLink.Create.CommandLine" Version="2.8.0" PrivateAssets="All" />

After that you can control the behaviour by setting the MSBuild property SourceLinkCreate=true. It should work out of the box with GitHub and Bitbucket, for GitLab, an additional switch is needed: SourceLinkServerType=GitLab

The PDB file gets now included with the NuGet package and will contain the reference to your original source in the Git repo (GitHub, Bitbucket or GitLab). At the time of writing, only public repos are supported.

When you open the PDB with DotPeek, then you should see the following reference:

    <Conversion FilePath="C:\dev\Some.Project\*" Uri="<commit>/*" />

This will tell the IDE (Visual Studio 2017 with update 3 and ReSharper) how to remap the underlying source code.

Next time when you're debugging and trying to step into an assembly with Source Link enabled, source will be fetched from the repo's public url automagically. Same applies when you want to see the class declaration. You can check the relevant diagnostic information from the output pane in Visual Studio.

Happy debugging!