Symbol Package Formats

When using the multi-feed approach for ProGet as your symbol server, one question that often comes up is whether to use the "new" or the "legacy" symbol format. This article will explain the difference between these two formats, and how they relate to ProGet.

What is a Symbol Package?

A symbol package is really just a NuGet package that has different contents and a .symbols.nupkg or .snupkg file extension. While this seems simple at first, it actually complicates things quite a bit, and causes some headaches.

NuGet packages are uniquely identified by their Id (e.g. FooBar.Utils) and Version (e.g. 3.4.1), which are contained in the package's .nuspec manifest file.

The package's file name has no bearing on this identification In fact, the NuGet client doesn't transmit file names to a feed when publishing packages. It doesn't need to, because packages are uniquely identified by Id and Version.

What this means is that there's no way to distinguish between the FooBar.Utils-3.4.1 and FooBar.Utils-3.4.1 NuGet package. There's no way to tell which FooBar.Utils-3.4.1 is a "library" package, and which FooBar.Utils-3.4.1 is a "symbols" package.

This is why you need two feeds when using symbol packages, and also why we generally recommend using the simple, single-feed approach outlined in ProGet as your symbol server.

Legacy Format (.symbols.nupkg)

.symbols.nupkg packages are considered to be legacy symbol packages, and can be created using the pack command on the nuget.exe client:

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

When created in this manner, a .symbols.nupkg file is exactly the same as the .nupukg file, but it includes .pdb files alongside the .dll files.

New Format (.snupkg)

.snupkg packages are the "new" format, and can be created using 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

When created in this manner, a .snupkg file will just like the
the .nupukg file, but there will be .pdb filesinstead of the .dll files and the .nuspec manifest file will be slightly different.

Which format to choose for ProGet?

When using a dedicated feed for your symbol server, it really doesn't matter to ProGet. They both "look" the same to ProGet, as they are both NuGet packages.

However, because .symbols.nupkg format is considered legacy, you should probably consider using the new format. In addition, the .snupkg files will be slightly smaller (they don't contain the .dll files), and who doesn't like saving a little disk space from time to time.