GitHub Source Symbol IndexerJan9

Monday, 9 January 2012 by haemoglobin

Do you host your .NET library on GitHub?

Do you want to give developers who use your library the ability to step into your code while debugging, without them even needing to have git installed or your repository cloned on their machines?

Then the GitHub Source Indexer could be for you.

The GitHub Source Indexer is a powershell script that will recursively iterate over PDB files in the directory you specify, indexing the source symbol server links back to raw GitHub HTTP urls, which Visual Studio will load while debugging.

This powershell script was adapted from SourcePack (by Sebastian Solnica) which can be used if you have the full source on your machine and packed into a zip file. In his article, he also describes a lot of the science behind the source indexing of PDB files which is useful reading. Much of the source of the script is reused from SourcePack (also hosted on codeplex here) so credits and thanks to Sebastian.

There is another tool SourceServer-GitExtensions but will require Git and the repository to be installed locally (we also had trouble getting this tool working).

The first requirement before running the script is to have the Debugging Tools for Windows installed which is part of the Windows SDK which can be downloaded from here: http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=8279

As part of the installation, ensure the Debugging Tools for Windows option is selected as part of the install (install or deselect other options as you desire):

Untitled

Once complete, add C:\Program Files\Debugging Tools for Windows (x64)\srcsrv (or wherever it installed itself on your machine) into your PATH environment variable.

The essential steps of using the script are as follows – all from the command prompt:

  1. Find out what paths are currently indexed in the pdb file:
    srctool –r YourLibrary.pdb
    The output should have a original file path for every source file used in the compilation, lets assume the following for the example:
    C:\git\TestRepository\YourLibrary\LibraryClass.cs
  2. We want this to link to a GitHub URL such as:
    http://github.com/[username]/[RepositoryName]/raw/[branchtagname]/YourLibrary/LibraryClass.cs
    Confirm this URL matches the same version of the source that was used when the PDB file was created. An real example URL can be seen here: https://github.com/Haemoglobin/TestRepository/raw/release1.0/ExampleLibrary/LibraryClass.cs
    This is what the Visual Studio debugger will download into the IDE and step into.
  3. Take note of the beginning of the path in the first step, which will tell the script what to strip out to replace with the GitHub URL, i.e C:\git\TestRepository
  4. Run the powershell script as follows:
    powershell .\github-sourceindexer.ps1 -symbolsFolder "C:\git\TestRepository\YourLibrary" -userId "Username" -repository "RepositoryName" -branch "branchtagname" -sourcesRoot "C:\git\TestRepository" –verbose
    Where:
    • -symbolsFolder: Directory to recurse to source index all PDB files.
    • -userId: Your GitHub username.
    • -repository: Your project’s GitHub repository name.
    • -branch: The name of the branch or tag that matches the correct versions of the source files as when the PDB file was created. 
    • -sourcesRoot: The path that we will be stripping out from the beginning of the original file paths found in step 3 above to replace with the GitHub URL. 
    • -verbose: A optional powershell flag to have the script output more output information to the console
    • Note: Watch out for escaping backslashes! For example use "C:\git\TestRepository" not "C:\git\TestRepository\" as the latter will escape the ending quote of the powershell parameter.
  5. Run the following against the PDB file to confirm the GitHub source indexing information was written:
    pdbstr –r –p:ExampleLibrary.pdb –s:srcsrv
    Which will look something like the following:
    SRCSRV: ini ------------------------------------------------
    VERSION=1
    INDEXVERSION=2
    VERCTL=Archive
    DATETIME=01/09/2012 11:58:22
    SRCSRV: variables ------------------------------------------
    SRCSRVVERCTRL=http
    HTTP_ALIAS=
    http://github.com
    HTTP_EXTRACT_TARGET=%HTTP_ALIAS%/%var2%/%var3%/raw/%var4%/%var5%
    SRCSRVTRG=%http_extract_target%
    SRCSRVCMD=
    SRCSRV: source files ---------------------------------------
    C:\git\TestRepository\YourLibrary\LibraryClass.cs*Haemoglobin*TestRepository*
    master*YourLibrary/LibraryClass.cs
    SRCSRV: end ------------------------------------------------

You can now distribute this PDB file along with your library’s DLL, and the developer will be able to step into your source library code to assist their debugging session. Alternatively to distributing the PDB file with your library, you could also make it available through a symbol server (which I may save for another blog post).

There are a couple of things that the developer will need to setup in Visual Studio however before they can step into the GitHub source your PDB files reference:

  1. Make sure the symbol cache directory is set to a writable location (if not running Visual Studio as administrator ensure that the non-elevated user also has permissions to write here):
    image
  2. Ensure source server support is enabled and Enable Just My Code is unticked:

DebuggingGeneral
That’s it!

To test this locally, copy and reference your library’s dll/pdb pair from another project, but make sure you rename your original library folder you compiled from. This is because the original file path is not actually removed in the source indexing process, so if it is still there Visual Studio will load the original path as opposed to downloading from GitHub.

Reference the library, write some code against it and add a breakpoint before the library call. Use F11 to step into the library code, and if the file correctly downloads from GitHub it should load from your symbol server cache directory, similar to below:

image

Good luck!

[Update: If you use Resharper, you will also be able to step into the library code on GitHub at development time as you are navigating around the code, so you don’t even need to be in a debugger session for this to happen. Nice!]

Categories:   Development
Actions:   E-mail | Permalink | Comments
blog comments powered by Disqus

Powered by BlogEngine.NET 1.6.1.0 | Design by styleshout | Enhanced by GravityCube.net | 1.4.5 Changes by zembian.com | Adapted by HamishGraham.NET
(c) 2010 Hamish Graham. Banner Image (c) Chris Gin