Source Link

Source Link 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 Source Link. Source Link is supported by Microsoft.

Source Link specification describes source control metadata that can be embedded in symbols, binaries and packages to link them to their original sources.

Visual Studio 15.3+ supports reading Source Link 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 Source Link implementation was provided by @ctaggart. Thanks! The .NET Team and Cameron worked together to make this implementation available in the .NET Foundation.

[!TIP] If you arrived here from the original Source Link documentation - you do not need to use SourceLink.Create.CommandLine.

Providing a good debugging experience for your project involves three main steps:

Including source control information in PDBs
Including source control information in the NuGet package manifest
Distributing PDBs

See below for examples and best practices regarding each step.

Using Source Link in .NET projects

Starting with .NET 8, Source Link for the following source control providers is included in the .NET SDK and enabled by default:

GitHub or GitHub Enterprise
Azure Repos git repositories (formerly known as Visual Studio Team Services)
GitLab 12.0+ (for older versions see GitLab settings)
Bitbucket 4.7+ (for older versions see Bitbucket settings)

If your project uses .NET SDK 8+ and is hosted by the above providers it does not need to reference any Source Link packages or set any build properties to include source control information in the PDB.

If your project does not yet use .NET SDK 8+, or is not hosted by one of the these providers, you must add a PackageReference to a Source Link package specific to the provider:

<Project>
  <ItemGroup>
    <!-- Add PackageReference specific for your source control provider (see below) -->
  </ItemGroup>

  <PropertyGroup>
    <!-- Optional (set by default in .NET SDK 8+): Embed source files that are not tracked by the source control manager in the PDB -->
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
  </PropertyGroup>
</Project>

[!TIP] Source Link is a development dependency, which means it is only used during build. It is therefore recommended to set PrivateAssets to all on the package reference. This prevents consuming projects from attempting to install Source Link.

[!NOTE] Referencing any Source Link package in a .NET SDK 8+ project overrides the Source Link version that is included in the SDK.

If your project produces a NuGet package, set PublishRepositoryUrl to include source control information in the package manifest:

<Project>
 <PropertyGroup>
    <!-- Optional: Publish the repository URL in the built .nupkg (in the NuSpec <repository> element) -->
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
  </PropertyGroup>
</Project>

Source Link packages are currently available for these source control providers:

github.com and GitHub Enterprise

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

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

Azure Repos (former Visual Studio Team Services)

For projects hosted by Azure Repos in git repositories reference Microsoft.SourceLink.AzureRepos.Git:

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.AzureRepos.Git" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

Azure DevOps Server (former Team Foundation Server)

For projects hosted by on-prem Azure DevOps Server in git repositories reference Microsoft.SourceLink.AzureDevOpsServer.Git and add host configuration like so:

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.AzureDevOpsServer.Git" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

You also need to provide the hostname of your DevOps server:

<ItemGroup>
  <SourceLinkAzureDevOpsServerGitHost Include="server-name"/>
</ItemGroup>

The Include attribute specifies the domain and optionally the port of the server (e.g. server-name or server-name:8080).

If your server is configured with a non-empty IIS virtual directory, specify this directory like so:

<ItemGroup>
  <SourceLinkAzureDevOpsServerGitHost Include="server-name" VirtualDirectory="tfs"/>
</ItemGroup>

GitLab

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

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitLab" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

Starting with version 8.0.0, Microsoft.SourceLink.GitLab assumes GitLab version 12.0+ by default. If your project is hosted by GitLab older than version 12.0 you must specify SourceLinkGitLabHost item group in addition to the package reference:

<ItemGroup>
  <SourceLinkGitLabHost Include="gitlab.yourdomain.com" Version="11.0"/>
</ItemGroup>

The item group SourceLinkGitLabHost specifies the domain of the GitLab host and the version of GitLab. The version is important since URL format for accessing files changes with version 12.0. By default Source Link assumes new format (version 12.0+).

You might also consider using environment variable CI_SERVER_VERSION (Version="$(CI_SERVER_VERSION)") if available in your build environment.

Bitbucket

For projects in git repositories hosted on Bitbucket.org or hosted on an on-prem Bitbucket server reference Microsoft.SourceLink.Bitbucket.Git package:

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.Bitbucket.Git" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

If your project is hosted by Bitbucket Server or Bitbucket Data Center older than version 4.7 you must specify SourceLinkBitbucketGitHost item group in addition to the package reference:

<ItemGroup>
  <SourceLinkBitbucketGitHost Include="bitbucket.yourdomain.com" Version="4.5"/>
</ItemGroup>

The item group SourceLinkBitbucketGitHost specifies the domain of the Bitbucket host and the version of Bitbucket. The version is important since URL format for accessing files changes with version 4.7. By default Source Link assumes new format (version 4.7+).

gitweb

For projects hosted on-prem via gitweb reference Microsoft.SourceLink.GitWeb package:

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitWeb" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

gitea

For projects hosted on-prem via gitea reference Microsoft.SourceLink.Gitea package:

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.Gitea" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

Multiple providers, repositories with submodules

If your repository contains submodules hosted by multiple git providers reference packages of all these providers, unless the project uses .NET SDK 8+ and submodules only use providers for which Source Link support is included. For example, projects in a repository hosted by Azure Repos that links a GitHub repository via a submodule should reference both Microsoft.SourceLink.AzureRepos.Git and Microsoft.SourceLink.GitHub packages. Additional configuration might be needed if multiple Source Link packages are used in the project.

Using Source Link in C++ projects

Source Link package supports integration with VC++ projects (vcxproj) and VC++ linker.

To add Source Link support to your native project add package references corresponding to your source control provider to packages.config direc

Sourcelink

Install / Use

README