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 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 in your own project hosted on GitHub by following this example:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netcoreapp2.1</TargetFramework>
<!-- Optional: Declare that the Repository URL can be published to NuSpec -->
<PublishRepositoryUrl>true</PublishRepositoryUrl>
<!-- Optional: Embed source files that are not tracked by the source control manager to the PDB -->
<EmbedUntrackedSources>true</EmbedUntrackedSources>
<!-- Optional: Include PDB in the built .nupkg -->
<AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0-beta-62925-02" PrivateAssets="All"/>
</ItemGroup>
</Project>
For projects hosted by Visual Studio Team Services in git repositories reference Microsoft.SourceLink.Vsts.Git package like so:
<PackageReference Include="Microsoft.SourceLink.Vsts.Git" Version="1.0.0-beta-62925-02" PrivateAssets="All"/>
If your repository contains submodules hosted by other git providers reference packages of all these providers. For example, projects in a repository hosted by VSTS that links a GitHub repository via a submodule should reference both Microsoft.SourceLink.Vsts.Git and Microsoft.SourceLink.GitHub packages.
Note that .NET SDK 2.1 RC1 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 |
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.