README.md

Source Link (preview*)

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 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 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.

If you arrived here from the original Source Link documentation - you do not need to use SourceLink.Create.CommandLine. You only need to install the packages listed below.

Preview Status

We recommend using Source Link preview for building production packages. Although the implementation details and the public APIs of the Source Link pre-release packages are still in flux, there will be no difference in the format of the data it generates between preview and 1.0.0. The only changes in the generated data we expect are due to bug fixes that target scenario that previously did not work correctly.

Using Source Link in .NET projects

You can enable Source Link experience in your own .NET project by setting a few properties and adding a PackageReference to a Source Link 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: Build symbol package (.snupkg) to distribute the PDB containing Source Link -->
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>
  <ItemGroup>
    <!-- Add PackageReference specific for your source control provider (see below) --> 
  </ItemGroup>
</Project>

If you distribute the library via a package published to NuGet.org, it is recommended to build a symbol package and publish it to NuGet.org as well. This will make the symbols available on NuGet.org symbol server, where the debugger can download it from when needed. Alternatively, you can include the symbols in the main package. However, doing so is not recommended as it increases the size of the package and thus restore time for projects that consume your package.

Source Link packages are currently available for the following source control providers.

Source Link package 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 of your nuget package from attempting to install Source Link.

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="1.0.0-beta2-18618-05" PrivateAssets="All"/>
</ItemGroup>

Azure DevOps (Visual Studio Team Services)

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-beta2-18618-05" PrivateAssets="All"/>
</ItemGroup>

Team Foundation Server

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-beta2-18618-05" 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).

GitLab

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

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitLab" Version="1.0.0-beta2-18618-05" PrivateAssets="All"/>
</ItemGroup>

Bitbucket.org

For projects hosted on Bitbucket.org in git repositories reference Microsoft.SourceLink.Bitbucket.Git package and add Bitbucket host configuration. Including flag whether it is Enterprise Edtition or Cloud. For Enterprise Edition provide its version and change value in include attribute to your Bitbucket server name:

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.Bitbucket.Git" Version="1.0.0-beta2-18618-05" PrivateAssets="All"/>
  <SourceLinkBitbucketGitHost Include="bitbucket.org" EnterpriseEdition="true" Version="4.1" />
</ItemGroup>

Multiple providers, repositories with submodules

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

<packages>
  <package id="Microsoft.Build.Tasks.Git" version="1.0.0-beta2-18618-05" targetFramework="native" developmentDependency="true" />
  <package id="Microsoft.SourceLink.Common" version="1.0.0-beta2-18618-05" targetFramework="native" developmentDependency="true" />
  <package id="Microsoft.SourceLink.GitHub" version="1.0.0-beta2-18618-05" targetFramework="native" developmentDependency="true" />
</packages>

Once the packages are restored and the project built the Source Link information is passed 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.

Prerequisites for .NET projects

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

.NET Core SDK 2.1.300 or newer is required for .NET SDK projects. If building via desktop msbuild you'll need version 15.7 or higher.

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

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

These features can be added via custom msbuild targets.

Prerequisites for C++ projects

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

The VC++ linker supports /SOURCELINK switch 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 in Visual Studio 2019.

Known issues

• EmbedUntrackedSources does not work in Visual Basic projects that use .NET SDK: dotnet#193 (fixed in Visual Studio 2019)
• Various build issues on Mono: dotnet#155
• Issues with WPF projects when building with /p:ContinuousIntegrationBuild=true: dotnet#91

Alternative PDB distribution

Prior availability of NuGet.org symbol server the recommendation used to be to include the PDB in the main NuGet package by setting the following property in your project:

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

Including PDBs in the .nupkg is generally no longer recommended as it increases the size of the package and thus restore time for projects that consume your package, regardless of whether the user needs to debug through the source code of your library or not. That said, .snupkg symbol packages have some limitations:

• They do not currently support Windows PDBs (generated by VC++, or for managed projects that set build property DebugType to full)
• 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 debugger.
• Not supported by Azure DevOps Artifacts service.

Consider including PDBs in the main package only if it is not possible to use .snupkg for the above reasons. For managed projects, consider switching to Portable PDBs by setting DebugType property to portable. This is the default for .NET SDK projects, but not classic .NET projects.

Builds

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

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Experience in Visual Studio

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