Ever tried debugging a NuGet package and slammed into a wall? Don’t worry, you’re not alone. Switching from debugging other package types to stack tracing your NuGet packages can be a massive headache, simply because NuGet packages are precompiled binaries. App crashes can seem impossible to fix—after all, how can you pinpoint the cause of an error when you can’t step-through your code to find the point of origin?

Symbol files can be a lifesaver for examining compiled code—especially for a package that’s gone through a few (or a few dozen) iterations—allowing you to step-through your compilations line by line, and see where your code actually broke down. But Symbol serving isn’t always enabled by default in Visual Studio, and many major private repositories don’t even offer Symbol-serving functionality.

In this article, we’ll cover what a Symbol server actually is, how Source Link fits into the picture, and how both can make debugging NuGet packages way less painful.

What is a Symbol Server?

Symbol files have been around way longer than NuGet or even .NET—like, decades longer (👴). Back when disk space was super limited, Symbols usually didn’t make the cut in published software, making debugging a massive headache.

That’s where Symbol Servers come in. When you build a library, the compiler embeds the same unique ID (basically a GUID) in both the .dll and .pdb files. Once uploaded to a Symbol Server, your debugger (say, Visual Studio) can grab the .pdb file later by matching that ID from the .dll file.

That’s how debuggers like Visual Studio pull the right Symbol files when your app crashes—no need to stash every .pdb file locally, since they can be fetched on the fly.

If you’re using a private NuGet repository like ProGet, it can index and serve those .pdb files too—as long as it’s set up beforehand. And don’t forget, your dev tools, like Visual Studio, also need also need setting up for your Symbol Server to work smoothly.

What is SourceLink?

Remember how a .pdb maps compiled files (like your .dll and .exe) back to your source code (.cs files)? Well, for that to work, you need the exact version of those source files that were used to build the assemblies. So… if you’re pulling Symbols from a server, where do those code files come in?

That’s where Source Link steps in. When you build a NuGet package with Source Link enabled, a Git repository URL and commit ID get embedded in the package metadata. This allows Visual Studio to locate the exact code files it needs at debug time.

Enabling Source Link in your own .NET projects, only means setting a few properties and then adding a NuGet package specific to your Git repository (e.g. Microsoft.SourceLink.GitHub).

How Does Symbol Serving Help with Debugging?

🌟 Symbol Servers and Symbols go hand-in-hand, helping the debugger find the right source files (from the Symbol Server). Since the .pdb files contain all the Symbol indexing info, you need those Symbols loaded to make it work.

🌟 And for stepping into the source code linked to a .pdb file, the Source Link Build tool can embed source file URLs (and even the source files themselves) during the build—making debugging way easier.

Better NuGet debugging

Yeah, debugging NuGet packages has a reputation for being painful, which is why many developers steer away from it altogether. Instead, they might duplicate code or avoid splitting projects into projects—just to keep debugging simple.

However, with a properly configured Symbol Server, it’s a totally different story. Tools like Source Link and ProGet make it much easier to step-through NuGet code and understand what’s happening under the hood.

There’s a lot to unpack here, so make sure to bookmark this page if you need a refresher! Or, for more insights, download our eBook, “NuGet at Scale“. It’s packed with information on debugging with Symbols and Source Link, managing vulnerabilities, and much more! Grab your free copy today!