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.

Additional documentation is on the wiki.

Here is the General, Debugging, Options Dialog Box from Visual Studio 2017:

Enable source server support

SourceLink v1 automates source indexing of Windows PDB files. It enables the source code repostiory to be the source server by updating the Windows PDB files with a source index of https links. Source indexing is done by modifying the Windows PDB file after a compile.

Enable source link support

SourceLink v2 helps enable source link support using the Portable PDB format. They are cross platform and several times smaller than Windows PDB files. The implementation and specification are open source. Source link support has documentation and is in the Portable PDB spec. The source link JSON file is built before the compile and the .NET compilers embeds it in the Portable PDB file. The compilers shipped with Visual Studio 2017 and with the DotNet SDKs support the /sourcelink option. Here is the relevant help from the C# compiler:

. "C:\Program Files\dotnet\sdk\1.0.0\Roslyn\RunCsc.cmd" /?

 /debug:{full|pdbonly|portable|embedded}
                               Specify debugging type ('full' is default,
                               'portable' is a cross-platform format,
                               'embedded' is a cross-platform format embedded into
                               the target .dll or .exe)
                               
 /embed                        Embed all source files in the PDB.
 
 /embed:<file list>            Embed specific files in the PDB
 
 /sourcelink:<file>            Source link info to embed into Portable PDB.

Quick Start

The source link 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. Simply add a PackageReference. A common way to do with is by adding it to your projects in a Directory.Build.props:

<Project>
  <ItemGroup>
    <PackageReference Include="SourceLink.Create.CommandLine" Version="2.6.0" PrivateAssets="All" /> 
  </ItemGroup>
</Project>

If you are building on Windows, make sure that you configure git to checkout files with core.autocrlf input.

By default SourceLink.Create.CommandLine will try to process GitHub and BitBucket cloned repositories. You can specify a specific server type by setting the SourceLinkServerType MSBuild property like /p:SourceLinkServerType=GitHub, /p:SourceLinkServerType=BitBucket, /p:SourceLinkServerType=BitBucketServer or /p:SourceLinkServerType=GitLab.

You can control when it runs by setting the SourceLinkCreate property. That property is set to true by default on build servers that set CI or BUILD_NUMBER environment variables. In general these tools are meant to be run only on build servers, but you can test locally by setting an MSBuild property like /p:ci=true or /p:SourceLinkCreate=true.

If you have a dotnet project, you can test locally with:

dotnet restore
dotnet build /p:ci=true /v:n

With an full framework project, you can test locally with:

msbuild /t:restore
msbuild /t:rebuild /p:ci=true /v:n

examples

• Rx.NET
• ASP.NET MVC

Test

dotnet sourcelink test is a tool you can use to test that the source link works. Source link support and this tool are not tied to git at all. It makes sure all links work for every source file in the PDB that is not embedded. 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.6.0" />

examples

• SourceLink build.ps1
• octokit.net using Cake

dotnet sourcelink test may also be run by using the SourceLink.Test MSBuild targets.

<PackageReference Include="SourceLink.Test" Version="2.6.0" PrivateAssets="all" />

Just like the SourceLinkCreate property, you can control when it is enabled by setting the SourceLinkTest property.

dotnet sourcelink-git

Please follow the quick start if you are just getting started. SourceLink.Create.CommandLine uses the git commandline by default, does not use dotnet, and has been easier for new users to understand.

SourceLink.Create.GitHub, SourceLink.Create.BitBucket and SourceLink.Create.BitBucketServer use dotnet sourcelink-git, which accesses the git information using libgit2sharp. This allows some additional features. It verifies that all of the source files are in the git repository and that their checksums match. If checksums do not match due to line endings, it will automatically fix them to match the git repository like endings of lf. If a source file's checksum still does not match, it will be embedded. If the source file is not in the git repository, it will be embedded. All of these settings are configurable.

<PackageReference Include="SourceLink.Create.GitHub" Version="2.6.0" PrivateAssets="all" />
<DotNetCliToolReference Include="dotnet-sourcelink-git" Version="2.6.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.

All Source Files

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

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

Paket Files

If you are using SourceLink.Create.CommandLine and Paket's support for including source code that is not in your repository, you can embed those files in the pdb with:

<PackageReference Include="SourceLink.Embed.PaketFiles" Version="2.6.0" PrivateAssets="all" />

Known Issues

Please vote for all of these issues:

• GitHub NuGet: msbuild /t:Pack always creates seperate symbols package

  dotnet pack and msbuild /t:pack do not include the pdb files by default. As of Visual Studio 2017 15.4 or .NET Core 2.0.2 SDK and above, you can fix this by modifying this property:

  <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>

  We may automatically set that property in the next version of SourceLink, see issue #282.

  The previous recommended way of including them was to use the extension point designed for including content that is different for each target framework:

  <PropertyGroup>
    <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);IncludePDBsInPackage</TargetsForTfmSpecificContentInPackage>
  </PropertyGroup>
  <Target Name="IncludePDBsInPackage" Condition="'$(IncludeBuildOutput)' != 'false'">
    <ItemGroup>
      <TfmSpecificPackageFile Include="$(OutputPath)\$(AssemblyName).pdb" PackagePath="lib\$(TargetFramework)" />
    </ItemGroup>
  </Target>

• Visual Studio User Voice: Debugger should support C# compiler '/embed' option

  The Visual Studio 2017 debugger does not currently look for embedded source files. The fix will ship with Visual Studio 2017 15.5.

• Visual Studio User Voice: Debugger should support authentication with SourceLink

  In order to use source link with private GitHub repositories and other private repositories, it needs to support authentication.