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.
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.
If you arrived here from the original sourcelink documentation - you do not need to use
SourceLink.Create.CommandLine. You only need to install the packages listed below.
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.
SourceLink package is a development dependency, which means it is only used during build. It is therefore recommended to set
allon the package reference. This prevents consuming projects of your nuget package from attempting to install SourceLink.
github.com and GitHub Enterprise
<ItemGroup> <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0-beta-63127-02" PrivateAssets="All"/> </ItemGroup>
Azure DevOps (Visual Studio Team Services)
<ItemGroup> <PackageReference Include="Microsoft.SourceLink.Vsts.Git" Version="1.0.0-beta-63127-02" PrivateAssets="All"/> </ItemGroup>
Team Foundation Server
<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:8080, etc.) and IIS virtual directory of the server (e.g.
<ItemGroup> <PackageReference Include="Microsoft.SourceLink.GitLab" Version="1.0.0-beta-63127-02" PrivateAssets="All"/> </ItemGroup>
<ItemGroup> <PackageReference Include="Microsoft.SourceLink.Bitbucket.Git" Version="1.0.0-beta-63127-02" PrivateAssets="All"/> </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 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.
EmbedUntrackedSourcesdoes not work in Visual Basic projects that use .NET SDK: https://github.com/dotnet/sourcelink/issues/193
- Various build issues on Mono : https://github.com/dotnet/sourcelink/issues/155
- Issues with OpenSSL dependency on some Linux distros: https://github.com/dotnet/sourcelink/issues/192
- Issues with WPF projects when building with
Pre-release builds are available on MyGet gallery: https://dotnet.myget.org/Gallery/sourcelink.
|x64 Debug||x64 Release|
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.