Debugging NuGet Packages in ABP.IO: A Complete Guide

cover

Ever found yourself struggling to understand what's happening inside a NuGet package while working with ABP Framework? Perhaps you've encountered unexpected behavior in Volo.Abp.Account or Volo.Abp.Identity but couldn't see what was actually going on under the hood.

The good news is that Visual Studio provides powerful tools that allow you to step directly into NuGet packages, observe their internal workings, and gain invaluable insights for troubleshooting and learning.

Why Debug NuGet Packages?

Before diving into the how-to, let's quickly understand why this capability matters:

  • Troubleshooting: Identify the root cause of issues that originate within package code
  • Learning: Understand how ABP Framework implements various features
  • Better Integration: See how your code should interact with ABP modules
  • Customization: Make informed decisions when overriding or extending ABP functionality

Prerequisites

  • Visual Studio 2019 or later
  • An ABP Framework project with NuGet packages you want to debug

Setting Up Visual Studio for NuGet Package Debugging

Let's walk through the process step by step:

1. Disable "Just My Code"

This is the first critical step that tells Visual Studio to allow debugging of external code.

  1. Open Visual Studio
  2. Navigate to Tools → Options
  3. In the Options dialog, select Debugging → General
  4. Uncheck the option labeled "Enable Just My Code"

Disable Just My Code

2. Configure Symbol Loading

Symbols (PDB files) provide the mapping between compiled code and source code, making debugging possible.

  1. In the Options dialog, go to Debugging → Symbols
  2. Check "Microsoft Symbol Servers" to download symbols from Microsoft's servers
  3. Check "NuGet.org Symbol Server" if available (or add https://symbols.nuget.org/download/symbols manually)
  4. Set a cache location for symbol files (the default is typically in your AppData folder)

Configure Symbol Servers

Source Link is a technology that helps the debugger locate and download source code from repositories.

  1. In the same Options dialog, ensure you're in Debugging → General
  2. Check "Enable Source Link support"
  3. For additional control, you can also check "Enable Source Server support"

Enable Source Link Support

Source Link is a vital technology that bridges the gap between compiled code and source code repositories. Here's what you need to know:

  • What is Source Link? It's a technology that embeds source control metadata into NuGet packages and assemblies, allowing debuggers to download the exact source code used to build those binaries.

  • How it Works: When you step into a method from a NuGet package, Source Link provides the debugger with information about where to find the corresponding source file in the original repository.

  • ABP Framework Compatibility: Most ABP.IO packages already support Source Link, making it possible to debug directly into their source code.

Debugging in Action: A Real-World Example

Let's say you're overriding the IdentityUserAppService in your application, and you want to understand how the base implementation works:

  1. First, place a breakpoint on your call to the base method:
public override async Task<IdentityUserDto> CreateAsync(IdentityUserCreateDto input)
{
    // Place breakpoint here
    var result = await base.CreateAsync(input);
    // Your custom code
    return result;
}
  1. Start debugging your application and navigate to the part that triggers this code
  2. When execution hits your breakpoint, press F11 (Step Into) to step into the base class implementation
  3. Visual Studio will:
    • Download necessary symbols (if not already cached)
    • Use Source Link to fetch the original source code
    • Open the source file and position the cursor at the method you're stepping into

image

  1. You can now debug through the ABP Framework code just like your own code:
    • Inspect variables
    • See the execution flow
    • Set additional breakpoints
    • Use all standard debugging features

Debugging ABP Commercial Modules

Commercial ABP modules (e.g., Volo.Saas, Volo.Payment, Volo.FormManagement) are not open-source and are distributed as obfuscated and encrypted DLLs. Consequently, Source Link does not support these modules, and you cannot debug them directly unless you have access to their source code .

What About ABP Commercial Packages?

Commercial packages like Volo.Saas, Volo.Payment, and Volo.FormManagement:

  • Are not Source Link enabled
  • Contain obfuscated and protected DLLs
  • Cannot be debugged unless you have direct source code access

✅ If You Have an ABP Commercial License:
You can access the source code directly:

  1. Follow the official guide
  2. Reference the source modules instead of NuGet packages
  3. You can then debug them like any other part of your app

⚠️ Do not attempt to decompile or reverse-engineer ABP Commercial DLLs — it violates licensing agreements.

Troubleshooting Common Issues

Symbols Not Loading

If you're unable to load symbols:

  1. Verify your symbol server settings are correct
  2. Check your internet connection (symbols need to be downloaded)
  3. Try clearing your symbol cache:
    • Go to Tools → Options → Debugging → Symbols
    • Click "Clear All Symbol Cache Directories"
  4. Ensure the package actually includes symbols (not all do)

Source Code Not Found

If symbols load but source code doesn't:

  1. Verify that "Enable Source Link support" is checked
  2. Check if the repository containing the source code is public
  3. For private repositories, you may need to configure authentication
  4. Try enabling verbose Source Link diagnostics to see what's happening

Performance Considerations

Debugging with symbols and Source Link can impact performance:

  1. Loading symbols and source files takes time, especially on first use
  2. Consider using the "Load only specified modules" option to load symbols selectively
  3. Once you're done debugging packages, re-enable "Just My Code" for normal debugging

Best Practices for ABP Development

When to Use NuGet Package Debugging

  • During troubleshooting of unexpected behavior
  • When learning how to properly extend ABP functionality
  • Before implementing complex customizations

When to Avoid It

  • For day-to-day development when you don't need to see inside packages
  • When performance is a concern
  • When you're already familiar with the internals

Conclusion

Stepping into NuGet packages is an invaluable skill for ABP developers. Whether you're troubleshooting complex issues, understanding how to properly extend the framework, or simply learning how ABP works under the hood, this technique provides insights that would otherwise be difficult to obtain.

Remember to toggle these settings only when needed, as they can impact your debugging performance. Once you're done exploring package internals, consider re-enabling "Just My Code" for your regular development workflow.

By mastering this technique, you'll be better equipped to work with ABP Framework effectively, troubleshoot issues faster, and create better integrations with the ABP ecosystem.

Additional Resources