Pdb2Github

This is the excellent tool provided by Hamish Graham, described here: http://hamishgraham.net/post/GitHub-Source-Symbol-Indexer.aspx

All I've done is package it up into a NuGet package, so it's easier to automate as part of your build.

Quick start

1. Add this NuGet package pdb2github to your project.

2. Edit your .csproj or .vbproj or .vcxproj file to invoke it. Here's an example, but you'll certainly need to hack around with paths to make it work for your project:

  <Target Name="AfterBuild">
    <PropertyGroup>
      <GithubUserId>__GITHUB_USERID__</GithubUserId>
      <GithubRepository>__GITHUB_REPOSITORY__</GithubRepository>
      <GithubCommitId>__GITHUB_COMMIT_ID__</GithubCommitId>
      <GithubRoot>$(MSBuildThisFileDirectory.Replace('\subfolder\',''))</GithubRoot>
    </PropertyGroup>

    <Exec WorkingDirectory="bin"
	       Command="powershell -ExecutionPolicy ByPass
                       ..\packages\pdb2github.1.0.0\tools\github-sourceindexer.ps1
                       -dbgToolsPath ..\packages\pdb2github.1.0.0\tools
                       -ignoreUnknown
                       -symbolsFolder .
                       -userId %22$(GithubUserId)%22
                       -repository %22$(GithubRepository)%22
                       -branch $(GithubCommitId)
                       -sourcesRoot %22$(GithubRoot)%22"
		   />
   </Target>

Explanation

When we add a NuGet reference to pdb2github in our project, it gets copied into either <Folder with .sln file>\packages\pdb2github.1.0.0 (if you're using NuGet2, recognized by the file packages.config in your project), or into %USERPROFILE%\.nugets\pakcages\pdb2github\1.0.0 (if you're using NuGet3, recognized by the file project.json in your project). The pdb2github nuget package has a "tools" subfolder, and we invoke a script from that subfolder. In this case we were using NuGet2 and wrote out the relative path to the packages directory from my current .csproj:

..\packages\pdb2github.1.0.0\tools\github-sourceindexer.ps1

Hamish's script needs to find a few other tools, which are also in the same directory:

-dbgToolsPath ..\packages\pdb2github.1.0.0\tools

The script will look recursively look for symbols in the -symbolsFolder directory. I set that to just ., which picks up the script's WorkingDirectory:

WorkingDirectory="bin"

-symbolsFolder .

The PDBs, as generated by C#/VB/C++ compilers, normally just have absolute paths to source files on disk, for instance c:\users\lwischik\documents\GitHubVisualStudio\myrepo\mysoln\myproj\a.vb. The script's job is to change this within the PDB into two possible paths, on on disk and the other on github, like this:

c:\users\lwischik\documents\GitHubVisualStudio\myrepo\mysoln\myproj\a.vb*ljw1004*myrepo*commitid*mysoln/myproj/a.vb

This way when a user consumers your library (and has access to the PDBs, and has gone to Tools > Options > Debugger to turn OFF Just My Code and to turn ON Enable Source Server Support), if the debugger can't find the file on disk, then it'll instead look for it on github.

The script needs to know which part of that file's path merely points to the repo (c:\users\lwischik\documents\GitHubVisualStudio\myrepo in this case) so it can deduce that the rest of the path is relative to the repo (mysoln/myproj/a.vb). I figured that out relative to the location of my current .csproj:

<PropertyGroup>
  <GithubRoot>$(MSBuildThisFileDirectory.Replace('\mysoln\myproj\',''))</GithubRoot>
</PropertyGroup>

-sourcesRoot %22$(MyRepositoryRoot)%22"

And the script needs to know the github user-id, github repository-name and github commit-id. It combines them all into a URL of them form

https://raw.githubusercontent.com/__GITHUB_USERID__/__GITHUB_REPOSITORY__/__GITHUB_COMMIT_ID__/mysoln/myproj/a.vb