- 27 May 2021
- 5 Minutes to read
-
Print
-
DarkLight
-
PDF
Symbol and Source Server
- Updated on 27 May 2021
- 5 Minutes to read
-
Print
-
DarkLight
-
PDF
A NuGet feed in ProGet may be configured as a Symbol/Source server compatible with debuggers such as Visual Studio and WinDbg. The following is supported by the ProGet symbol server:
☑ Microsoft PDB format (C/C++, .NET)
☑ Source server
☑ Portable PDB format (.NET)
☒ PDBs in connector packages
☒ Source server for ProGet on Linux
How to Access Symbols
When the Symbol Server is enabled, any symbols files stored in local Feed packages will be accessible via the symbol server URL:
http://«proget-server»/symbols/«Feed»
Creating Symbol Packages
ProGet supports both NuGet "symbol packages" that were created with the Symbols
argument, as well as NuGet packages that contain "embedded" symbols.
See the NuGet documentation on building a symbol package for detailed information on how to create symbol packages.
Single-Feed Approach (Embedded)
The simplest, and recommended, approach is to simply include PDB files inside your NuGet package. This involves setting the DebugType
property on your project file to embedded
.
<PropertyGroup>
<DebugType>embedded</DebugType>
</PropertyGroup>
Once you've done that, when you push your package to ProGet, you will now be able to use ProGet's symbol server.
.symbol.nupkg
Packages Note
The DebugType
property may not be available on all project types, and all versions of your tooling. If that command doesn't embed your .pdb
files, then you can use the Symbols
argument to generate a .symbol.nupkg
package file, and push that instead of the .nupkg
package.
The main downside to the single-feed approach is that symbol files will be downloaded with your package. However, this is easy to prevent by using the Strip symbol files from packages downloaded from this feed option on the Manage Feed page under Symbol Server settings.
Multi-feed Approach (Symbol Packages)
By default, NuGet will produces two packages (one with symbols and one without). This is because one package is intended to be pushed to package-only feed (e.g. nuget.org), while the other is intended to be pushed to a symbol server (e.g. symbols.nuget.org).
Do not push a library package and its symbol package to the same feed. They will simply overwrite each other.
The main downside to this approach is that you will need to maintain two feeds (MyPackages
and MyPackageSymbols
for example).
Pushing Symbol Packages
By default, when you use the nuget push
command, if there is a symbols package present, then the symbol package will be pushed to the default symbol server (e.g. symbols.nuget.org). You need to specify the symbol-source
argument to change this default url.
If you're doing a single push command, then you will likely need to specify the symbol-source
url.
dotnet nuget push foo.nupkg --source
http://«proget-server»/nuget/«feed» --symbol-source
http://«proget-server»/nuget/«symbols-feed»
If you're pushing only the symbols package, then the source
argument is used.
dotnet nuget push foo.snupkg --source
http://«proget-server»/nuget/«symbols-feed»
PDB Formats and Source Serving
ProGet will index and serve portable PDB files as well as the traditional Microsoft PDB files, but portable PDB files are not transparently rewritten to enable them to work with source code in the embedded NuGet package.
If you would like to debug into the source code associated with a portable PDB file, consider using a build tool such as SourceLink to embed source file URLs (or the files themselves) during compilation.
If you would like support for rewriting portable PDB files in the same way ProGet handles Microsoft PDB files, let us know
Configuring ProGet
In order for ProGet to serve symbols for a particular NuGet feed, it must be configured to do so. Visit the Manage Feed page, and ensure that the options under Symbol Server are correctly checked, while noting the URL of the feed's symbol server to be used within Visual Studio:
Verifying Indexed Symbols
Once a package with symbols is uploaded to the feed, browsing to the Package Details page will indicate whether symbols have been indexed and whether the package contains sources:
You can download the package and inspect it yourself to verify this using the Download Package with Symbols link (which appears if the feed is configured to strip symbols).
Configuring Visual Studio
Enable Symbol Server Support
In order to debug into NuGet package libraries, Visual Studio must be configured to use ProGet as a symbol server. Select Debug > Options... from the menu bar, then browse to Debugging > Symbols in the tree menu. Add the symbol server URL found on the Manage Feed page earlier, and specify a Symbol Cache Directory. By default Visual Studio will use %LOCALAPPDATA%\Temp\SymbolCache
, but you may specify any path.
Enable Source Server Support
To configure source server support, browse to Debugging > General in the debugging options tree menu, and make sure the following settings are checked/unchecked as follows:
☐ Enable Just My Code
☑ Enable source server support
Additionally, you may have to uncheck:
☐ Enable .NET Framework Source Stepping
in some cases. The settings should look like the following:
Testing the Configuration
A simple way to test out the configuration is to create a console application that consumes the NuGet package with symbols, write some throwaway code that you know will throw an exception, then click the Start button in Visual Studio to begin debugging:
If everything is configured correctly, Visual Studio will attempt to load symbols locally, then query the ProGet symbol server if they cannot be found, and the exact line that throws the exception will become highlighted:
Troubleshooting
In some cases, the symbol server will fail for any number of reasons, the most common being misconfiguration. To view the
PDBs that Visual Studio has loaded, select the Debug > Windows > Modules menu option while debugging, and find the desired DLL in the list. The symbol status will appear, along with the version and path to both the DLL and the downloaded symbols.
Whether the symbols loaded or not, you can right-click on the DLL and select "Symbol Load Information..." to view the diagnostic messages associated with the symbol server for that library.
The hex string in the file path should also start with the GUID listed in ProGet:
Common Errors
The most common errors (based on previous support inquiries) include:
- Using the wrong URL, e.g. chttp://«proget-server»/nuget/«feed-name» instead of the correct http://«proget-server»/symbols/«feed-name»
- Pushing both NuGet packages (with and without symbols)
- Trying to consume symbols for connector packages (which is not supported, workaround is to pull packages locally or use a separate feed for symbols)
- Not including source files under the
/src/
directory at the root of the .nupkg file - Configuring a Symbol Server will cause the package to be re-created when pulled into ProGet. This may cause NuGet Error NU3008 in your applications.