A few weeks ago, I started to stream on twitch, and the following question popped out: how can I easily debug my NuGet libraries?

On this blog, I have already talked about how you can create and version a NuGet package, but in this post, I want to talk about how you can debug it after the deployment.

I’m sure the list showed here is not complete, and there are many other ways you can achieve the same task, but these are the ones I’ve tried in my work experience:

• NuGet Remote Server + Symbol files (PDB)
• NuGet Local Server + Symbol files (PDB)
• Package Reference Switcher (Visual Studio Extension)
• Switch references with a PowerShell script
• Reference the DLL directly

Let’s have a look at each one of them in detail. In this scenario, I suppose you want to debug and fix a bug in a NuGet package. You have access to the source code of both the library and the project that references it as a package, but they are not in the same Visual Studio solution.

NuGet Remote Server + Symbol files (PDB)

During the NuGet package creation, it is possible to generate symbol files too. If you are not familiar with them, a good definition is the following (from Microsoft documentation):

“Program database (.pdb) files, also called symbol files, map identifiers, and statements in your project’s source code to corresponding identifiers and instructions in compiled apps.”

Symbol files help to debug the code because they map the source code with compiled code and allow the step-by-step within it when a breakpoint is set.

There are many ways to create a symbol file: for example, if you are using the .NET Core CLI, the pack command can generate a Symbols Package (.snupkg) which contains the PDB file with the following parameters:

dotnet pack MyPackage.csproj -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg

Once created, a PDB file must be available for debugging using a Symbol Server or putting it directly into the bin folder of the project that references the library. The first approach is much reliable because it is more reproducible, especially if a CI/CD system such as Azure DevOps is in place. In this case, the pipeline publishes both the package and the symbol file (note: Azure Artifacts has an integrated Symbol Server). Another cool thing is that these PDBs are cross-platforms (check here for more info)!

To debug the library, add the Symbol Server in Visual Studio, as shown here.

Figure 1: Adding a symbol server in Visual Studio

If a bug is detected, you should fix the code in the library project and commit it to the source code. This action will trigger the build pipeline to create both the package and the symbol file again and upload the package on the NuGet Server of your own choice. After, you need to update the reference in your project.

Despite the reliable workflow, launching a build to generate the package could slow down your process, especially if you have not entirely tested it. The next paragraph explains how to overcome this problem.

NuGet Local Server + Symbol files (PDB)

Did you know that a NuGet server can be created from a local folder? If you did not, these are the steps to follow:

1. Create a folder;
2. Execute the nuget sources add -Name LocalNuget -Source <local-nuget-folder> command to add the NuGet source;
3. Push the package using this command dotnet nuget push <nupkg-files> -s <local-nuget-folder>;
4. Add the updated package to your executable project and start testing.

The annoying part is that, to debug into the code, you should manually copy the PDB to the bin folder of our executable project. Besides, the main difference between the previous approach is that the CI/CD pipeline will not be triggered until all fixes are completed.

Package Reference Switcher (Extension)

Package Reference Switcher is a Visual Studio Extension that allows switching a NuGet package with a project (.csproj) and vice versa. The extension is available here: https://marketplace.visualstudio.com/items?itemName=RicoSuter.NuGetReferenceSwitcherforVisualStudio2019. After installed it in Visual Studio, go to Tools and select “Switch NuGet and Project references,” which opens a window to change the references. You can replace a NuGet package using a project in the same solution or anywhere on your machine. Once completed the testing, you can switch back to the package and update it if necessary.

Figure 2: Package Reference Switcher option in Visual Studio

Figure 3: Switch reference in Package Reference Switcher

This extension is beneficial, but I’ve noticed that it doesn’t wholly support .NET Core yet (an error appears). Indeed, the author suggests using another project of his, which could anticipate the next solution: https://github.com/RicoSuter/DNT (does the author’s name ring a bell?). This project is a command-line utility to manage packages and references and supports .NET Core projects.

Switch references with a PowerShell script

Package Reference Switcher awakened the PowerShell aficionado in me. Practically, the idea behind this approach is simple, and thanks to the .NET Core CLI, I can achieve the same goal in a few minutes. What I need to know is:

• Library Project location
• Solution Location
• Executable Project location
• Package Name
• A bit of .NET Core CLI commands

An example of the script could be the following:

Switch-Reference.ps1
param(
    [switch]$ToReferences
)
if($ToReferences)
{
    # Add the library project to the solution
    dotnet sln <solution_file> add <library_project_file>
    # Add the library reference to the executable project
    dotnet add <executable_project_file> reference <library_project_file>
    # Remove the NuGet package reference
    dotnet remove <executable_project_file> package <package_name>
}
else
{
    # Remove the library from solution
    dotnet sln <solution_file> remove <library_project_file> 
    # Remove the library reference
    dotnet remove <executable_project_file> reference <library_project_file>
    # Restore the NuGet package reference
    dotnet add <executable_project_file> package <package_name>
}

During the execution, I can switch between the project or the package passing the flag “-ToReference.”

Despite the initial effort to configure the commands, I found this script very handy.

Reference the DLL directly

The last approach is to switch the NuGet package reference with the project manually; or you can even reference the DLL directly from the Bin folder of the library project. To be honest, I strongly advise against this approach. It’s error-prone, and you can quickly introduce unexpected behavior or wrong references.

Which method should I use?

Let me summarize using this table:

I prefer the first solution if there are multiple projects to debug (and I do not develop one or more of them!) or, if the scenario is simple, the PowerShell script. Sometimes I mix the two approaches.

Happy debug!