There are several documented ways on internet on how to use Symbols Source files and Source Link to debug inside a Nuget Package but it's honestly hard to understand what is the good way for me.
We have an Azure DevOps Server on which we generate Nuget packages and at the same time publish the .pdb
files to the Azure DevOps Symbol Server using an Index Sources & Publish Symbols
task in our build pipelines as described here
My project' also has a reference to Microsoft.SourceLink.Vsts.Git
and this code in the .csproj
file
<PublishRepositoryUrl>true</PublishRepositoryUrl>
<EmbedUntrackedSources>true</EmbedUntrackedSources>
I've read several blog posts but the source I trust the most to be up to date is of course the official Source Link Git repository.
The readme.md
file says
Including PDBs in the .nupkg is generally no longer recommended as it increases the size of the package and thus restore time for projects that consume your package, regardless of whether the user needs to debug through the source code of your library or not
I agree with that point that's why I want to use the Symbol Server, not to include the .pdb
file in the Nuget Package. Therefore please don't flag my question as a duplicate of this one, because the accepted answer is exactly what I don't want to do.
The readme file also states that
.snupkg symbol packages have some limitations:
- They do not currently support Windows PDBs (generated by VC++, or for managed projects that set build property DebugType to full)
- They require the library to be built by newer C#/VB compiler (Visual Studio 2017 Update 9).
- The consumer of the package also needs Visual Studio 2017 Update 9 debugger.
- Not supported by Azure DevOps Artifacts service.
so at least I know I can't use that.
But what is the proper way to set Source Link up and working then?
When I debug my test console application it successfully downloads the .pdb
file to my Symbols cache folder but if I try to step in the code coming from my Nuget Package using F11
, it just doesn't work. (However it steps in System.String.Concat
because my simple test Nuget Package is actually concatenating some strings)
I tried to run sourcelink test TestSourceLink.pdb
but I get a error: url hash does not match
. I read here that sourcelink test
is a legacy thing and doesn't support authentication to private repositories like ours.
With my browser, if I visit the URL given by sourcelink print-json TestSourceLink.pdb
I can see the latest source code. But now the question is, why is Visual Studio not able to download the source code? I'm authenticated to this Azure DevOps server in VS because I'm able to install Nuget Packages coming from this server.
Here are my debugging settings:
Thanks a lot. I really can't figure out what's the missing piece of this puzzle
Well, I should have read and followed this answer before posting my question because this was the missing piece of the puzzle.
I needed to follow steps 5 and 6 of Eric's blog post but I actually didn't need to modify my pack
command because I'm not including the .pdb
file in the Nuget Package.
[EDIT 2]:
Note: So far I could only get this working if the Nuget Package is generated with the Debug Build Configuration. If you find a way to get Source Link working with a Release DLL inside the Nuget Package, please answer my other question. Thank you
[EDIT]: Since I wrote a documentation for my company, here it is:
Summary:
This requires two things:
- Having access to the Symbol file of the project (
.pdb
) which is a mapping file used by the debugger
- Enable Source Link support so Visual Studio knows where it should look to download the source code while debugging
Set Up:
Component's project
For each project in your solution:
Only if you plan consumers of the Nuget package to use Visual Studio 2017. This step isn't required with you want to use Source Link with Visual Studio 2019:
In Visual Studio, right click on your project -> Properties
then go to Build -> Advanced
and change the Debugging Information
from Portable
(default value) to Full
Install the Microsoft.SourceLink.AzureDevOpsServer.Git Nuget Package
Edit the .csproj
file and include the following code in the first PropertyGroup
element:
<PublishRepositoryUrl>true</PublishRepositoryUrl>
<EmbedUntrackedSources>true</EmbedUntrackedSources>
Azure DevOps build pipeline
Create a pipeline variable called BuildConfiguration
(if it doesn't exist already) and set the value to Debug
- Use this variable as argument in your
.NET Core Build
task: --configuration $(BuildConfiguration)
- In your
.NET Core Pack
task, use this variable in the Configuration to Package
field: $(BuildConfiguration)
At the end of your pipeline you must have a task Index Sources & Publish Symbols
- In the
Artifact name
field, the BuildConfiguration
variable must be used too: Symbols_$(BuildConfiguration)
Of course you must also have a .NET Core Push
task to push you Nuget package to your Azure DevOps Nuget Feed
Visual Studio
Tools -> Options -> Debugging -> Symbols
click on the New Azure DevOps Symbol Server Location...
button and authenticate to the server
- Set the cache folder to a convenient location like
C:\Symbols\
. This is where all your .pdb
files will be stored
Tools -> Options -> Debugging -> Symbols
click on Load only specified modules
. You can here specify the Symbol files of DLLs you want to load.
If you don't do this and leave the default to Load all modules, unless excluded
, Visual Studio will take a very long time to load everything when you run your program in debug mode.
Tips : To see all the DLLs loaded by your project, when you're debugging, click on Debug -> Windows -> Modules
. From here you can view the full list, select multiple and then right click Copy Value -> Copy Name
Tools -> Options -> Debugging -> General
- Uncheck
Enable Just My Code
- Check
Enable source server support
- Check
Enable Source Link Support
Consuming project
When you want to debug inside the Nuget Package's code, naturally press F11
to step into it and Visual Studio will ask if you agree to download the source code from your Azure DevOps repository