Source Linking

Let us define "source linking" as more than just source indexing. It is web linking a .NET assembly (dll or exe) via http or https to the source files in a source control system and revision used to create it. When you debug into the assembly, the debugger is able to download the exact source code on demand directly from the code repository exposed on the web. It provides traceability.

Better solution than SymbolSource

It is a decentralized solution. Any builds can be source linked as part of the build process without noticeable overhead. Traceability to the revision of the source code is provided. It may be used with hosted private repositories. It may be used behind the corporate firewall. It does not send your username and computer name over http with every source file request. Does anyone else think this to be a security concern and not a good idea (snippet from my post in March)?

SRCSRVTRG=http://srv.symbolsource.org/pdbsrc/Public/public/42b47598-1b3c-4204-a801-5d4e7621ffd2/%CN%/%UN%/Mono.HttpUtility/8791519FDC5A4CF994F009F69BC7C4B62/%var2%
SRCSRVCMD=
UN=%USERNAME%
CN=%COMPUTERNAME%
SRCSRVVERCTRL=http

Announcing: SourceLink

SourceLink is a project to help make source linking possible. The code is under the Apache License 2.0. I wrote .NET code to update a pdb file. It is able to read all the source file checksums from the pdb. It is also able to write a srcsrv stream to the pdb like "pdbstr -w" does.

SourceLink MSBuild Targets 0.2

Source linking should work with any source control system that supports accessing files for a particular revision via the web like git, mercurial, svn, and tfs. I've started with git support. I uploaded SourceLink.Build 0.2 to NuGet last night. It is feature complete for git. Please use it and report back! Any bugs can be logged to the issue tracker.

It makes use of a cool new feature of NuGet 2.5 that allows auto importing of MSBuild targets. When you add this NuGet package, no assembly references will be added to your project. This line will be added to the bottom of your MSBuild project file (csproj or fsproj). NuGet is smart enough to update it when you update the package or remove it when you remove the package.

 <Import Project="..\packages\SourceLink.Build.0.2\build\SourceLink.Build.targets" Condition="Exists('..\packages\SourceLink.Build.0.2\build\SourceLink.Build.targets')" />

To enable source linking, you need to add a couple properties to the project file. The first is the URL that will be used to download the source code. It is ok if the code hasn't been pushed to the repository yet. Using libgit2sharp as an example, the URL is:

<SourceLinkRepoUrl>https://raw.github.com/libgit2/libgit2sharp/{0}/%var2%</SourceLinkRepoUrl>

The {0} is where the revision will go and the %var2% is where the source file path will go. This is an example of a constructed source code URL:

https://raw.github.com/libgit2/libgit2sharp/afb9cf4edaca91f9b8718805376888781f5cef21/LibGit2Sharp/Repository.cs

To turn on source linking, add this property. It can be conditionally set for a particular configuration or passed in on the command line. A typical scenario will be to put this in the release configuration properties:

<SourceLink>true</SourceLink>

After adding those two properties, simply reload the project and build it. It will verify that the checksums of the source files match what is in the git repository and what is in the pdb file. If the checksums do not match, you will get an appropriate error. If they do match, the pdb file will be updated with the source links. As an example, building the LibGit2Sharp outputs:

An optional property that was needed for LibGit2Sharp was to exclude a file that does not get committed. Multiple files can be set using a semicolon as the separator.

<SourceLinkExclude>Core\UniqueIdentifier.cs</SourceLinkExclude>

You can set another optional property to get the srcsrv stream written to a txt file also. It will still be written to the pdb.
<SourceLinkWriteSrcSrvTxt>true</SourceLinkWriteSrcSrvTxt>

Another way to verify that the srvsrv stream got written to the pdb is to use pdbstr.

The source file URLs can be checked using srctool.

It would be nice to construct these URLs via code. A tool could be written to verify the pdb by downloading all the files and verifying the checksums.

Line Endings

If the source files that you build with have different line endings that what is in the git repository, then the checksums will not match. SourceLink will make sure that the checksums match and provide you errors if they do not. Use the appropriate git settings.

Several projects have builds with different line endings than what is in their repository. This causes problems with loading the source files into the debugger. SourceLink will make sure this does not happen.

Include the source linked pdb files!

I am hoping to spark a shift in the open source .NET world to including source linked pdb files. I would like to see them included in the packages on NuGet. This potentially makes SymbolSource obsolete. It makes the source code more open and easier to access.