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.