2017-03-05

Enable source link support & Announcing SourceLink 2.0

I'm very excited about Visual Studio 2017 launching on this Tuesday, March 7th. Visual Studio 2017 has a new debugging option called "Enable source link support". It is a redesign of "Enable source server support".  They both have the same goal of providing access to the source code while you are debugging.



Source server support is limited to the Windows PDB files. Source link support is designed for Portable PDB files. The compilers support Portable PDB files for .NET Framework too, not just .NET Core.

Here is relevant help from the C# compiler in the latest dotnet sdk:

. "C:\Program Files\dotnet\sdk\1.0.0-rc4-004771\Roslyn\RunCsc.cmd" /?

 /debug:{full|pdbonly|portable|embedded}
                               Specify debugging type ('full' is default,
                               'portable' is a cross-platform format,
                               'embedded' is a cross-platform format embedded into
                               the target .dll or .exe)

 /embed                  Embed all source files in the PDB.

 /embed:                 Embed specific files in the PDB

 /sourcelink:            Source link info to embed into Portable PDB.

Debug types of full and pdbonly create the older Windows PDB files. Debug types of portable and embedded create the newer Portable PDB files. Windows PDB files are often much bigger than the .dll or .exe. Portable PDB files are often about 20% of the size the target .dll or .exe, so we recommend embedded with source link enabled.

Announcing SourceLink 2.0

SourceLink version 2.0 is a set of build tools to help create and test for source link support. They do not add any run-time dependencies. Here are the 2.0.0 build artifacts, built on AppVeyor:

They are tiny. There are a couple of dotnet CLI tools and an MSBuild wrapper for GitHub. Please see the readme for full documentation on them. The CLI tools are so small because dotnet CLI will load the dependencies. In the case of dotnet-sourcelink-git, they are:


Simple

Embedding the Portable PDB in the .dll and .exe files with source link info makes things simple. We don't have to create symbols packages and ship the source to a third party. The debuggers don't have to looks for PDB files in symbol servers or scattered around shared file systems. The information is contained in the the .dll and .exe, only adding about 20% in file size.

It is worth highlighting that some dotnet pack options are obsolete with this solution. I consider these options to be apart of the legacy "Enable source server support":

PS> dotnet pack --help
.NET Core NuGet Package Packer

Options:
  --include-symbols       Include packages with symbols in addition to regular packages in output directory.
  --include-source        Include PDBs and source files. Source files go into the src folder in the resulting nuget package

With "Enable source link support", debugging can just be much simpler. Imagine creating a new ASP.NET Core MVC app and being able to debug into its source code without doing anything special. If my pull request gets merged, this will be the case.

Adding SourceLink 2.0 to your project is very simple. It is just a matter of adding a couple of references and making sure your build server checks out line endings as is with core.autocrlf=input.

If you'd like to see BitBucket support, Mercurial or Subversion support, etc, please open an issue on GitHub and see the contributing section on the wiki. Cheers!
at