Setting up GitHub Source Linking with Azure DevOps Services Build & Azure DevOps Services Symbol Server
Azure DevOps Services now includes an integrated symbol server. When you run a build, PDB files are produced which you can upload to the symbol server. These symbols can then be later downloaded to debug production issues, or by other developers in your organization that might be reusing the code that you have published into a package. By default Azure DevOps Services makes it very easy to index and publish symbols for source code that is hosted and built within Azure DevOps Services, but did you know that you can also publish symbols for source code that is hosted on GitHub?
When building .NET code in Azure DevOps Services the Index and Publish Symbols build task is responsible finding PDB files and inserting source file location information into them so that when they are later downloaded the debugger knows where to locate source files. The symbols task is included by default in build pipeline templates. All you need to do is check the Publish Symbols parameter to get started.
For source code that is hosted in Azure DevOps Services, that is all you need to do. However, for source code that is hosted on GitHub and being built in Azure DevOps Services you need to do a few extra steps.
In order to publish symbols to and download symbols from the Azure DevOps Services Symbol Server you must have the Azure Artifacts extension installed.
Installing the Source Link Package
Azure DevOps Services doesn't natively know how to map source code that originated from a GitHub repository so we need to give it a bit of a hand. To do that you need to install the
SourceLink.Create.CommandLine package into your solution. This injects the logic necessary to map source code hosted in GitHub to symbols stored in PDB files so that the Visual Studio debugger can seamlessly download source files as another developer steps through your code.
Modifying the Build Pipeline
The next step is to modify the build pipeline to invoke Source Link. This is done by adding a
/p:SourceLinkCreate=true parameter to the MSBuild task.
Once this is done you can save and queue the build pipeline and the GitHub source linking information will be embedded into the PDBs prior to be publishing to the symbol server in Azure DevOps Services.
You may notice that during the build process a warning is still produced by the Index and Publish Symbols task that it cannot index the source code because it is not hosted in Azure DevOps Services. You can ignore this warning because the source location information was embedded earlier in the build process via the Source Link tooling.
Verifying the Setup
Once the build has been completed and the symbols have been published it is time to make sure that everything is working as expected. Before attaching the debugger to your target process you should ensure that you have configured Visual Studio to download symbols from Azure DevOps Services and use the Source Link information embedded in those symbols to download source from GitHub.
To point Visual Studio to Azure DevOps Services for downloading symbols click on Tools, then Options and then scroll down to the Debugging group of items and select Symbols item. Use the New Azure DevOps Services Symbol Server location icon to select your Azure DevOps Services server and add it to the list of symbols locations.
Next select the General item under the Debugging group and scroll down and check the Enable Source Link support.
Now that Visual Studio is setup it is time to attach the debugger to the process that is running the code that you want to download symbols for. Once the debugger is attached Visual Studio will attempt to locate symbols for each binary by probing Azure DevOps Services, if the symbols are found then it will download the PDB files.
In order to trigger the download of source code you need to break into the running process. The first time Visual Studio attempts to download the source code it will prompt for consent.
Once consent is granted Visual Studio will download the source files directly from GitHub and display then in the editor with the break point highlighted.
When attaching to a process, you may need to uncheck the Enable Just My Code option unde the Debugging | General options.
In this article we've shown you how to get up and running using the symbol server integrated with Azure DevOps Services even when your source code is coming from GitHub.
Does this work with private GitHub repositories?
No, currently the Source Link implementation in Visual Studio is not designed to work with authenticated GitHub repositories. This functionaly is being added in will be available in the future release of Visual Studio 2017.