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.Vsts.Git Nuget Package (You must check the Include prerelease checkbox in Visual Studio)
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