Search code examples
visual-studiodebuggingreleasenuget

Best practices with Nuget: Debug or Release?

Currently, I package the release builds with Nuget for the official builds to nuget.org, but I package the debug builds with Nuget for the symbol source pushes to symbolsource.org.

EDIT: (Jon Skeet, with some bias from Noda Time development)

NuGet now supports pushing to both NuGet gallery and symbolsource.org (or similar servers), as documented. Unfortunately, there are two contradictory requirements here:

  • When just using a library without any need for debugging, you really want a release build. That's what release builds are for, after all.
  • When debugging into a library for diagnostic purposes, you really want a debug build with all the appropriate optimizations disabled. That's what debug builds are for, after all.

That would be fine, but NuGet doesn't (as far as I can tell) allow both the release and debug builds to be published in a useful way, in the same package.

So, the choices are:

  • Distribute the debug builds to everyone (as shown in the example in the docs) and live with any size and performance hits.
  • Distribute the release builds to everyone and live with a slightly impaired debug experience.
  • Go for a really complicated distribution policy, potentially providing separate release and debug packages.

The first two really boil down to the effect of the differences between debug and release builds... although it's worth noting that there's also a big difference between wanting to step into the code of a library because you want to check some behaviour, and wanting to debug the code of a library because you believe you've found a bug. In the second case, it's probably better to get the code of the library as a Visual Studio solution and debug that way, so I'm not paying too much heed to that situation.

My temptation is to just keep with the release builds, with the expectation that relatively few people will need to debug, and the ones who do won't be impacted much by the optimizations in the release build. (The JIT compiler does most of the optimizing anyway.)

So, are there other options we hadn't considered? Are there other considerations which tip the balance? Is pushing NuGet packages to SymbolSource sufficiently new that "best practice" really hasn't been established?

Solution

  • It's been 8 years since OP's post (with previous answer still top-voted below), so I'll give it a crack with what's used nowadays.

    There are 2 ways of "stepping into" a NuGet package:

    1. Distribution of PDBs

    .symbols.nupkg symbol packages are considered as legacy and have been replaced with .snupkg packages that get published to Symbol Server. It’s supported by most vendors with Azure DevOps being the biggest outsider where the feature request is still "under review" (thank you @alv for the link).

    Here are the official instructions. Simply add these two lines to the csproj file:

    <PropertyGroup>
  <IncludeSymbols>true</IncludeSymbols>
  <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>

    On the consumer side, make sure that your IDE is configured for the NuGet.org (or Azure, etc.) Symbol Server to allow stepping into package code when debugging.

    2. Source Link.Linking the actual code

    In some cases, the PDBs may hide some specifics of the source code due to MSIL/JIT optimisation. So there is a way of ”Stepping Into” the actual source of your NuGet while debugging. It’s called Source Link from the .NET Foundation – ”a language- and source-control agnostic system for providing source debugging experiences for binaries“.

    It’s supported by Visual Studio 15.3+ and all the major vendors (also supports private repos).

    It’s trivial to setup (official docs) – just add a development dependency to the project file (depends on the type of your repo) along with some flags:

    <PropertyGroup>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="All" />
</ItemGroup>

    Check out more on this subject in "5 steps to better NuGet package".