SourceLink

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.

.NET Foundation

SourceLink is a .NET Foundation project. It joined in 2017-11.

License

SourceLink is licensed under the MIT license.

Quick Start

The source link support documention shows how to embed a source link file by running git commands. That is exactly how the targets file for SourceLink.Create.CommandLine works. 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 Directory.Build.props:

<Project>
  <ItemGroup>
    <PackageReference Include="SourceLink.Create.CommandLine" Version="2.8.0" 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 /p:SourceLinkCreate=true.

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

As of SourceLink 2.7, the pdb files will automatically be included in your nupkg if you use dotnet pack or msbuild /t:pack. This makes the MSBuild properties /p:IncludeSymbols=true and /p:IncludeSource=true obsolete and you may safely disable those options.

Test

dotnet sourcelink test is a command you can use to test that the source link works. It makes sure all links work for every source file that is not embedded in the PDB. You can test a nupkg, a pdb, or a dll if the pdb is embedded. Run dotnet sourcelink for a list of other diagnostic commands and additional help.

Install by adding:

<DotNetCliToolReference Include="dotnet-sourcelink" Version="2.8.0" />

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. Here is an example of specifying files to be embedded.

All Source Files

If you just want to embed all of the source files in the pdb and not use source link support, add this package:

<PackageReference Include="SourceLink.Embed.AllSourceFiles" Version="2.8.0" PrivateAssets="all" />

Documentation

Additional documentation is on the wiki.

Known Issues

New project system does not copy PDBs from packages when targeting .NET Framework

Add SourceLink.Copy.PdbFiles to your project file. See #313 for details.

<Project>
  <ItemGroup>
    <PackageReference Include="SourceLink.Copy.PdbFiles" Version="2.8.0" PrivateAssets="All" /> 
  </ItemGroup>
</Project>

Private repositories are not supported

Visual Studio 2017 15.6 may add support. Please vote for User Voice: Debugger should support authentication with SourceLink.
Visual Studio does not debug into embedded source files

Update to Visual Studio 2017 15.5 or later. Support was added.

Community

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the .NET Foundation Code of Conduct.

sagmor / SourceLink