- 27 May 2021
- 2 Minutes to read
-
Print
-
DarkLight
-
PDF
Symbol Package Formats
- Updated on 27 May 2021
- 2 Minutes to read
-
Print
-
DarkLight
-
PDF
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.