Symbol and Source Server

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.

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).

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.