Adding SourceLink to your .NET Core Library

by Carlos Mendible on 25 Aug 2018 » dotNetCore

Last week I read this tweets from Maxime Rouiller (@MaximRouiller):

Then I found out that SourceLink is a language-and source-control agnostic system for providing first-class source debugging experiences for binaries.”

What that means is that, once you enable SourceLink, the users are able to step into your code without effort! from both Visual Studio and Visual Studio Code which are ready to let you enjoy the experience.

This findings triggered my interest and started wondering on how could I add such a nice feature to the netDumbster project.

Here is what I did:

1. Added the following properties to the project’s csproj

<PublishRepositoryUrl>true</PublishRepositoryUrl>
<EmbedUntrackedSources>true</EmbedUntrackedSources>
<AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>

2. Added the following ItemGroup to the project’s csproj

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

Note: this Package Reference depends on the source control system.

3. Finally built the nuget package as usual

dotnet pack -c release

Believe me that was all!!! So then I tested the new package and features with a simple console application and Visual Studio Code:

1. Created a new console project

mkdir SourceLinkTest
cd SourceLinkTest
dotnet new console
dotnet add package netDumbster -v 2.0.0.3
dotnet restore

2. Replaced the contents of Program.cs with the following code

using System;
using netDumbster.smtp;
using netDumbster.smtp.Logging;

namespace a
{
    class Program
    {
        static void Main(string[] args)
        {
            LogManager.GetLogger = type => new ConsoleLogger(type);
            SimpleSmtpServer.Start();
        }
    }
}

3. Generated Assets for Build and Debug for .NET

Inside Visual Studio Code and from the Command Palette invoke the .NET: Generate Assets for Build and Debug command so it creates the launch.json and tasks.json files inside the .vscode folder.

4. Replace the contents of launch.json with the following configuration

{
   // Use IntelliSense to find out which attributes exist for C# debugging
   // Use hover for the description of the existing attributes
   // For further information visit https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger-launchjson.md
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (console)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            // If you have changed target frameworks, make sure to update the program path.
            "program": "${workspaceFolder}/bin/Debug/netcoreapp2.1/SourceLinkTest.dll",
            "args": [],
            "cwd": "${workspaceFolder}",
            // For more information about the 'console' field, see https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger-launchjson.md#console-terminal-window
            "console": "internalConsole",
            "stopAtEntry": false,
            "internalConsoleOptions": "openOnSessionStart",
            "justMyCode": false,
            "suppressJITOptimizations": true
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach",
            "processId": "${command:pickProcess}"
        }
    ,]
}

Note: the configuration disables justMyCode and enables suppressJITOptimizations.

I added a breakpoint in line 12 of Program.cs and started debugging. Once the debugger hit the breakpoint I pressed F11 to “Step Into” the netDumbster code. And surprise! I was in!!!

image shows the debugger inside netDumbster's code

Now let me ask you something: What are you waiting to get out there and add SourceLink to your existing library?

Hope you enjoyed the ride!