Source link support allows source code to be downloaded on demand while debugging. SourceLink is a set of build tools to help create and test for source link support. Source link support is a developer productivity feature that allows unique information about an assembly's original source code to be embedded in its PDB during compilation.
SourceLink is now a .NET Foundation project at https://github.com/dotnet/sourcelink/. It joined in 2017-11. Announced for .NET Core 2.1, much of the SourceLink support has been integrated into the SDK.
New tools from https://github.com/dotnet/sourcelink/ are in beta. They are shipped in the NuGet Gallery as Microsoft.SourceLink.*
1.0.0-beta*. They currently work on Windows and Ubuntu, but will soon support the rest.
Most of the SourceLink 2 tools from this repository are made obsolete by the .NET SDK 2.1 and Microsoft.SourceLink tools. This repository will still continue to fill in gaps in tooling. SourceLink 3 tools from this repository will be tools that build on top of the .NET SDK 2.1. The first and only tool for 3.0 is a
sourcelink command-line tool for testing for source link support.
dotnet tool install --global sourcelink
sourcelink is a tool to test that the source link enabled nupkg or pdb file work. It tests all source files listed in the pdb. You can also print diagnostic information for a pdb. Run
sourcelink without any options for a list of diagnostic commands and help:
SourceLink 3.0.0 Source Code On Demand Usage: [options] [command] Options: -h|--help Show help information Commands: print-documents print the documents stored in the pdb or dll print-json print the Source Link JSON stored in the pdb or dll print-urls print the URLs for each document based on the Source Link JSON test test each URL and verify that the checksums match Use " [command] --help" for more information about a command.
For SourceLink 2, it is just a dotnet cli tool, run as
dotnet sourcelink and installed by adding:
<DotNetCliToolReference Include="dotnet-sourcelink" Version="2.8.3" />
Please use the Microsoft.SourceLink.* tools if you are able to.
SourceLink.Create.CommandLine is the most successful SourceLink 2 tool. It contains a MSBuild targets file that runs
git commands by default to figure out the source repository to link to. Add this
PackageReference to each project that you wish to enable source link support for. See the wiki if you are using Paket. A common way to add this for multiple projects is to use a
<Project> <ItemGroup> <PackageReference Include="SourceLink.Create.CommandLine" Version="2.8.3" PrivateAssets="All" /> </ItemGroup> </Project>
Without any additional configuration
SourceLink.Create.CommandLine will work with GitHub and Bitbucket cloned repositories. See the wiki for additional options.
You can control when it runs by setting the MSBuild property
If you have a dotnet project, you can test locally with:
dotnet restore dotnet build /p:SourceLinkCreate=true /v:n
With an full framework project, you can test locally with:
msbuild /t:restore msbuild /t:rebuild /p:SourceLinkCreate=true /v:n
Package PDB in nupkg
Please package the pdb files in the nupkg files. It is strongly encouraged by Microsoft to do so. This obsoletes the MSBuild properties
/p:IncludeSource=true. You do not need the obsolete SymbolSource.
The new project system does not copy PDBs from packages when targeting .NET Framework #313. The simplest workaround until .NET SDK 2.1.400 ships in VS 15.8 timeframe is to add this reference:
<Project> <ItemGroup> <PackageReference Include="SourceLink.Copy.PdbFiles" Version="2.8.3" PrivateAssets="All" /> </ItemGroup> </Project>
Embedding Source Files
For source files are not committed to the repository, it is helpful to embed them, so that they are available while debugging. Source files are not committed often when generated or downloaded from elsewhere. The .NET SDK allows you to set EmbedUntrackedSources.
All Source Files
If you just want to embed all of the source files in the pdb and not use source link support, the .NET SDK allows you to set EmbedAllSources.
- Visual Studio 2017 15.8 is expected to have additional private repository support
- Visual Studio 2017 15.7 added support for source link to authenticated Github.com and VSTS repositories
- Visual Studio 2017 15.5 added support for debugging into embedded source files
SourceLink is licensed under the MIT license.
Additional documentation is on the wiki.