Repository files navigation

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 buildingNuGet 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 Linkspecification 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 fromraw.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.

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

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

1. Including source control information in PDBs
2. Including source control information in the NuGet package manifest
3. Distributing PDBs

See below for examples and best practices regarding each step.

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

• GitHub orGitHub Enterprise
• Azure Repos git repositories (formerly known as Visual Studio Team Services)
• GitLab 12.0+ (for older versions seeGitLab settings)
• Bitbucket 4.7+ (for older versions seeBitbucket 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>

If your project produces a NuGet package, setPublishRepositoryUrl 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:

For projects hosted byGitHub orGitHub Enterprise referenceMicrosoft.SourceLink.GitHub like so:

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

For projects hosted byAzure Repos in git repositories referenceMicrosoft.SourceLink.AzureRepos.Git:

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

For projects hosted by on-premAzure DevOps Server in git repositories referenceMicrosoft.SourceLink.AzureDevOpsServer.Git and add host configuration like so:

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

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

<ItemGroup>  <SourceLinkAzureDevOpsServerGitHostInclude="server-name"/></ItemGroup>

TheInclude attribute specifies the domain and optionally the port of the server (e.g.server-name orserver-name:8080).

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

<ItemGroup>  <SourceLinkAzureDevOpsServerGitHostInclude="server-name"VirtualDirectory="tfs"/></ItemGroup>

For projects hosted byGitLab referenceMicrosoft.SourceLink.GitLab package:

<ItemGroup>  <PackageReferenceInclude="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 specifySourceLinkGitLabHost item group in addition to the package reference:

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

The item groupSourceLinkGitLabHost 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 variableCI_SERVER_VERSION (Version="$(CI_SERVER_VERSION)") if available in your build environment.

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

<ItemGroup>  <PackageReferenceInclude="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 specifySourceLinkBitbucketGitHost item group in addition to the package reference:

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

The item groupSourceLinkBitbucketGitHost 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+).

For projects hosted on-prem viagitweb referenceMicrosoft.SourceLink.GitWeb package:

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

For projects hosted on-prem viagitea referenceMicrosoft.SourceLink.Gitea package:

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

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 bothMicrosoft.SourceLink.AzureRepos.Git andMicrosoft.SourceLink.GitHub packages.Additional configuration might be needed if multiple Source Link packages are used in the project.

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 topackages.config directly or usingNuGet Package Manager UI in Visual Studio. For example, thepackages.config file for a project hosted on GitHub would include the following lines:

<packages>  <packageid="Microsoft.Build.Tasks.Git"version="8.0.0"targetFramework="native"developmentDependency="true" />  <packageid="Microsoft.SourceLink.Common"version="8.0.0"targetFramework="native"developmentDependency="true" />  <packageid="Microsoft.SourceLink.GitHub"version="8.0.0"targetFramework="native"developmentDependency="true" /></packages>

Once the packages are restored and the project built the Source Link information ispassed to the linker and embedded into the generated PDB.

The only feature currently supported is mapping of source files to the source repository that is used by the debugger to find source files when stepping into the code. Source embedding and embedding commit SHA and repository URL information in the native binary are not supported for native projects.

Source Link supports classic .NET Framework projects as well as .NET SDK projects, that is projects that importMicrosoft.NET.Sdk (e.g. like so:<Project Sdk="Microsoft.NET.Sdk">). The project may target .NET, .NET Framework or .NET Standard. All PDB formats are supported: Portable, Embedded and Windows PDBs.

.NET 8 SDK or newer is required for .NET SDK projects. If building via desktopmsbuild you'll need version 16.0 or higher.

The following features are not available in projects that do not importMicrosoft.NET.Sdk:

• Automatic inclusion of commit SHA inAssemblyInformationalVersionAttribute.
• Automatic inclusion of commit SHA and repository URL in NuSpec.

These features can be added via custom msbuild targets.

Debugging native binary with Source Link information embedded in the PDB is supported since Visual Studio 2017 Update 9.

The VC++ linker supports/SOURCELINKswitch since Visual Studio 2017 Update 8, however the PDBs produced by this version are not compatible with case-sensitive source control systems such as git. This issue is fixed inVisual Studio 2019.

• Issue when building WPF projects with embedding sources on andBaseIntermediateOutputPath not a subdirectory of the project directory:#492

There are three main ways to distribute PDBs for managed code: via a dedicated .snupkg, including them in the main package, and embedding them directly into the assembly. Each has advantages and drawbacks, depending on your use case.

If you distribute the library via a package published toNuGet.org, it is recommended to build asymbol package and publish it toNuGet.org as well. This will make the symbols available onNuGet.org symbol server, where the debugger can download it from when needed.

.snupkg symbol packages have following limitations:

• They do not support Windows PDBs (generated by VC++, or for managed projects that set build propertyDebugType tofull)
• They require the library to be built by newer C#/VB compiler (Visual Studio 2017 Update 9).
• The consumer of the package also needs Visual Studio 2017 Update 9 or newer.
• Not supported byAzure DevOps Artifacts service.

If a .snupkg does not work for your scenario, consider including debug information in the main package via one of the alternatives.

You can include PDB files in the main NuGet package by setting the following property in your project:

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

You can embed Portable PDB debug information directly in the assembly by setting the following property in your project:

<PropertyGroup>  <DebugType>embedded</DebugType></PropertyGroup>

Pre-release builds are available from Azure DevOps public feed:https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet9/nuget/v3/index.json (browse).

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