SourceLink is a language- and source-control agnostic system for providing first-class source debugging experiences for binaries. The goal of the project is to enable anyone building NuGet libraries to provide source debugging for their users with almost no effort. Microsoft libraries, such as .NET Core and Roslyn have enabled SourceLink. SourceLink is supported by Microsoft.

SourceLink is a set of packages and a specification for describing source control metadata that can be embedded in symbols, binaries and packages.

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.

The original SourceLink implementation was provided by @ctaggart. Thanks! The .NET Team and Cameron worked together to make this implementation available in the .NET Foundation.

You can enable SourceLink experience in your own project by setting a few properties and adding a PackageReference to a SourceLink package:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
 
    <!-- Optional: Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
 
    <!-- Optional: Embed source files that are not tracked by the source control manager in the PDB -->
    <EmbedUntrackedSources>true</EmbedUntrackedSources>

    <!-- Optional: Include the PDB in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
  <ItemGroup>
    <!-- Add PackageReference specific for your source control provider (see below) --> 
  </ItemGroup>
</Project>

SourceLink packages are currently available for the following source control providers.

For projects hosted by GitHub or GitHub Enterprise reference Microsoft.SourceLink.GitHub like so:

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

For projects hosted by Azure DevOps in git repositories reference Microsoft.SourceLink.Vsts.Git:

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

For projects hosted by on-prem Team Foundation Server in git repositories reference Microsoft.SourceLink.Tfs.Git and add TFS host configuration like so:

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.Tfs.Git" Version="1.0.0-beta-63127-02" PrivateAssets="All"/>
  <SourceLinkTfsGitHost Include="tfs-server-name" VirtualDirectory="tfs"/>
</ItemGroup>

SourceLinkTfsGitHost item specifies the domain and optionally the port of the TFS server (e.g. myserver, myserver:8080, etc.) and IIS virtual directory of the server (e.g. tfs).

For projects hosted by GitLab reference Microsoft.SourceLink.GitLab package:

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

For projects hosted on Bitbucket.org in git repositories reference Microsoft.SourceLink.Bitbucket.Git package:

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

If your repository contains submodules hosted by other git providers reference packages of all these providers. For example, projects in a repository hosted by Azure DevOps that links a GitHub repository via a submodule should reference both Microsoft.SourceLink.Vsts.Git and Microsoft.SourceLink.GitHub packages. Additional configuration might be needed if multiple SourceLink packages are used in the project.

Note that .NET Core SDK 2.1.300 or newer is required for SourceLink to work. If building via desktop msbuild (as opposed to dotnet build) you'll need version 15.7.

Pre-release builds are available on MyGet gallery: https://dotnet.myget.org/Gallery/sourcelink.

	x64 Debug	x64 Release
Windows
Ubuntu 16.04
CentOS7.1		N/A
Debian8.2		N/A
RHEL7.2		N/A
OSX10.12		N/A

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

The following screenshot demonstrates debugging a NuGet package referenced by an application, with source automatically downloaded from GitHub and used by Visual Studio 2017.