You’ve heard of Symbols and Symbol packages. They’re a great tool for debugging your NuGet packages – some of the most fiddly packages to debug.

What’s the best way to get started with them? What repositories support them?

In this quick explainer, we’ll go over what exactly Symbols and Symbol packages are and how to format them in your next project.

Symbols vs. Symbol Packages

Symbols, a.k.a PDB files, map compiled code like .dll and .exe files to original .cs source code files.

A Symbol Package is just a NuGet package that contains symbol files. They have file extensions like .symbols.nupkg or .snupkg.

Two Symbol Types:

There are two types of symbol files: Microsoft PDB and Portable PDP.

Microsoft PDB is an older format. It can optionally have instructions that point Visual Studio to download mapped .cs files from a specialized Source Server like ProGet, and use embedded .cs files in the NuGet package to return the source code to Visual Studio.

Portable PDB is a newer format. It works cross-platform (unlike Microsoft PDB), but doesn’t support Source Server. Instead, you’ll need to use SourceLink to embed source files URLs in the NuGet package during compiling.

Three Symbol Package Formats

There are three Symbol Package formats you can use for your debugging process.

1) .symbols.nupkg is a legacy format but is still supported for compatibility. a .symbols.nupkg file is like a regular .nupkg file but includes .pdb files alongside the .dll files.

You can create this format using the pack command on the nuget.exe client:

nuget.exe pack MyPackage.nuspec -Symbols
nuget.exe pack MyProject.csproj -Symbols

2) .snupkg is the new format, though when creating a Symbol Package .symbols.nupkg is the default. Nuget.org’s symbol server only accepts the .snupkg format.

You create this type of package by specifying the SymbolPackageFormat on either the nuget.exe CLI or the dotnet CLI.

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

This format creates a .snupkg file – very similar to a regular .nupkg file but with .pdb files instead of the .dll files and the .nuspec manifest file will be slightly different.

3) .nupkg is an embedded format and the most straightforward (and recommended) approach, especially with ProGet. They include the PDB and DLL inside a single NuGet package.

This involves setting the DebugType property on your project file to embedded.

<PropertyGroup>
<DebugType>embedded</DebugType>
</PropertyGroup>

The embedded format lets you easily push a package to ProGet and its symbol server.

Try debugging with Symbols

Anyone who has hated debugging their NuGet packages should try Symbols and Symbol packages as a potential solution. There are other methods to debugging NuGet, like munging, but with ProGet’s symbol support, we absolutely recommend giving Symbols a try.

Did you find this article helpful? Are you using NuGet to make your .NET packages? Learn how to optimize your NuGet in the Enterprise; sign up for our free NuGet guide: