Exploring .NET Core’s SourceLink – Stepping into the Source Code of NuGet packages you don’t own

According to https://github.com/dotnet/sourcelink, SourceLink "enables a great source debugging experience for your users, by adding source control metadata to your built assets."

Sound fantastic. I download a NuGet to use something like Json.NET or whatever all the time, I'd love to be able to "Step Into" the source even if I don't have laying around. Per the GitHub, it's both language and source control agnostic. I read that to mean "not just C# and not just GitHub."

Visual Studio 15.3+ supports reading SourceLink information from symbols while debugging. It downloads and displays the appropriate commit-specific source for users, such as from raw.githubusercontent, enabling breakpoints and all other sources debugging experience on arbitrary NuGet dependencies. Visual Studio 15.7+ supports downloading source files from private GitHub and Azure DevOps (former VSTS) repositories that require authentication.

Looks like Cameron Taggart did the original implementation and then the .NET team worked with Cameron and the .NET Foundation to make the current version. Also cool.

Let me see if this really works and how easy (or not) it is.

I'm going to make a little library using the 5 year old Pseudointernationalizer from here. Fortunately the main function is pretty pure and drops into a .NET Standard library neatly.

I'll put this on GitHub, so I will include "PublishRepositoryUrl" and "EmbedUntrackedSources" as well as including the PDBs. So far my CSPROJ looks like this:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>

    <TargetFramework>netstandard2.0</TargetFramework>

    <PublishRepositoryUrl>true</PublishRepositoryUrl>

    <EmbedUntrackedSources>true</EmbedUntrackedSources>

    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>

  </PropertyGroup>

</Project>

Pretty straightforward so far. As I am using GitHub I added this reference, but if I was using GitLab or BitBucket, etc, I would use that specific provider per the docs.

<ItemGroup>

  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0-beta-63127-02" PrivateAssets="All"/>

</ItemGroup>

Now I'll pack up my project as a NuGet package.

D:githubSourceLinkTestPsuedoizerCore [master ≡]> dotnet pack -c release

Microsoft (R) Build Engine version 15.8.166+gd4e8d81a88 for .NET Core

Copyright (C) Microsoft Corporation. All rights reserved.


  Restoring packages for D:githubSourceLinkTestPsuedoizerCorePsuedoizerCore.csproj...

  Generating MSBuild file D:githubSourceLinkTestPsuedoizerCoreobjPsuedoizerCore.csproj.nuget.g.props.

  Restore completed in 96.7 ms for D:githubSourceLinkTestPsuedoizerCorePsuedoizerCore.csproj.

  PsuedoizerCore -> D:githubSourceLinkTestPsuedoizerCorebinreleasenetstandard2.0PsuedoizerCore.dll

  Successfully created package 'D:githubSourceLinkTestPsuedoizerCorebinreleasePsuedoizerCore.1.0.0.nupkg'.

Let's look inside the .nupkg as they are just ZIP files. Ah, check out the generated *.nuspec file that's inside!

<?xml version="1.0" encoding="utf-8"?>

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">

  <metadata>

    <id>PsuedoizerCore</id>

    <version>1.0.0</version>

    <authors>PsuedoizerCore</authors>

    <owners>PsuedoizerCore</owners>

    <requireLicenseAcceptance>false</requireLicenseAcceptance>

    <description>Package Description</description>

    <repository type="git" url="https://github.com/shanselman/PsuedoizerCore.git" commit="35024ca864cf306251a102fbca154b483b58a771" />

    <dependencies>

      <group targetFramework=".NETStandard2.0" />

    </dependencies>

  </metadata>

</package>

See under repository it points back to the location AND commit hash for this binary! That means I can give it to you or a coworker and they'd be able to get to the source. But what's the consumption experience like? I'll go over and start a new Console app that CONSUMES my NuGet library package. To make totally sure that I don't accidentally pick up the source from my machine I'm going to delete the entire folder. This source code no longer exists on this machine.

I'm using a "local" NuGet Feed. In fact, it's just a folder. Check it out:

D:githubSourceLinkTestAConsumerConsole> dotnet add package PsuedoizerCore -s "c:usersscottdesktopLocalNuGetFeed"

  Writing C:UsersscottAppDataLocalTemptmpBECA.tmp

info : Adding PackageReference for package 'PsuedoizerCore' into project 'D:githubSourceLinkTestAConsumerConsoleAConsumerConsole.csproj'.

log  : Restoring packages for D:githubSourceLinkTestAConsumerConsoleAConsumerConsole.csproj...

info :   GET https://api.nuget.org/v3-flatcontainer/psuedoizercore/index.json

info :   NotFound https://api.nuget.org/v3-flatcontainer/psuedoizercore/index.json 465ms

log  : Installing PsuedoizerCore 1.0.0.

info : Package 'PsuedoizerCore' is compatible with all the specified frameworks in project 'D:githubSourceLinkTestAConsumerConsoleAConsumerConsole.csproj'.

info : PackageReference for package 'PsuedoizerCore' version '1.0.0' added to file 'D:githubSourceLinkTestAConsumerConsoleAConsumerConsole.csproj'.

See how I used -s to point to an alternate source? I could also configure my NuGet feeds, be they local directories or internal servers with "dotnet new nugetconfig" and including my NuGet Servers in the order I want them searched.

Here is my little app:

using System;

using Utils;


namespace AConsumerConsole

{

    class Program

    {

        static void Main(string[] args)

        {

            Console.WriteLine(Pseudoizer.ConvertToFakeInternationalized("Hello World!"));

        }

    } 

}

And the output is [Ħęľľő Ŵőřľđ! !!! !!!].

But can I step into it? I don't have the source remember...I'm using SourceLink.

In Visual Studio 2017 I confirm that SourceLink is enabled. This is the Portable PDB version of SourceLink, not the "SourceLink 1.0" that was "Enable Source Server Support." That only worked on Windows..

You'll also want to turn off "Just My Code" since, well, this isn't your code.

Now I'll start a Debug Session in my consumer app and hit F11 to Step Into the Library whose source I do not have!

Fantastic. It's going to get the source for me! Without git cloning the repository it will seamlessly let me continue my debugging session.

The temporary file ended up in C:UsersscottAppDataLocalSourceServer4bbf4c0dc8560e42e656aa2150024c8e60b7f9b91b3823b7244d47931640a9b9 if you're interested. I'm able to just keep debugging as if I had the source...because I do! It came from the linked source.

Very cool. I'm going to keep digging into SourceLink and learning about it. It seems that if YOU have a library or published NuGet either inside your company OR out in the open source world that you absolutely should be using SourceLink.

You can even install the sourcelink global tool and test your .pdb files for greater insight.

D:githubSourceLinkTestPsuedoizerCore>dotnet tool install --global sourcelink

D:githubSourceLinkTestPsuedoizerCorebinreleasenetstandard2.0>sourcelink print-urls PsuedoizerCore.pdb

43c83e7173f316e96db2d8345a3f963527269651 sha1 csharp D:githubSourceLinkTestPsuedoizerCorePsuedoizer.cs

https://raw.githubusercontent.com/shanselman/PsuedoizerCore/02c09baa8bfdee3b6cdf4be89bd98c8157b0bc08/Psuedoizer.cs

bfafbaee93e85cd2e5e864bff949f60044313638 sha1 csharp C:UsersscottAppDataLocalTemp.NETStandard,Version=v2.0.AssemblyAttributes.cs

embedded

Think about how much easier consumers of your library will have it when debugging their apps! Your package is no longer a black box. Go set this up on your projects today.

Sponsor: Rider 2018.2 is here! Publishing to IIS, Docker support in the debugger, built-in spell checking, MacBook Touch Bar support, full C# 7.3 support, advanced Unity support, and more.