Debug against Release

Every project has two build configurations. Debug is the default of dotnet run: no optimization, the DEBUG symbol defined, and the information a debugger needs. Release optimizes the code and defines no DEBUG. The same source is two programs with two speeds.

The two configurations

A command chooses the configuration with -c:

The measured program

The program sums fifty million small values through a method call, five times, and reports the minimum and the median. The method is static and tiny, which is exactly the shape an optimizer inlines and a Debug build does not:

using System.Diagnostics; var runs = new List<double>(); long total = 0; for (var run = 0; run < 5; run++) { var watch = Stopwatch.StartNew(); total = 0; for (var i = 0; i < 50_000_000; i++) { total += Step(i); } watch.Stop(); runs.Add(watch.Elapsed.TotalMilliseconds); Console.WriteLine($"run {run + 1} {runs[^1]:F2} ms"); } Console.WriteLine($"min {runs.Min():F2} median {runs.Order().ElementAt(2):F2}"); Console.WriteLine($"total {total}"); static int Step(int value) => value % 7;

dotnet run

run 1 714.83 ms
run 2 607.38 ms
run 3 563.57 ms
run 4 789.47 ms
run 5 1021.07 ms
min 563.57 median 714.83
total 149999997

dotnet run -c Release

run 1 243.05 ms
run 2 245.09 ms
run 3 242.52 ms
run 4 392.90 ms
run 5 409.13 ms
min 242.52 median 245.09
total 149999997

Debug against Release

ConfigurationMin msMedian msTotal
Debug563.57714.83149 999 997
Release242.52245.09149 999 997

Both configurations printed the same total, which is the correctness check: an optimization must not change the answer. The Release median was about a third of the Debug one, because the method call was inlined into the loop and the arithmetic was arranged better. The Release runs also spread less: a Debug build spends time in code the runtime has to keep inspectable.

#if DEBUG

The DEBUG symbol is defined by the SDK in the Debug configuration, and #if DEBUG compiles a block only there. Trace and Debug.Assert use it, and a program may too:

#if DEBUG Console.WriteLine("debug build"); #else Console.WriteLine("release build"); #endif Console.WriteLine($"checked {Check(3)}"); static int Check(int value) { #if DEBUG if (value < 0) { throw new ArgumentOutOfRangeException(nameof(value)); } #endif return value * 2; }

dotnet run -c Release

release build
checked 6

The same program with dotnet run prints debug build instead. A check inside #if DEBUG costs nothing in Release, which is the point of the symbol and also its danger: a program that relies on the check behaves differently in the build a user runs. A validation of user input belongs outside the conditional; a check of an internal invariant may live inside it.

Exercises

  1. Remove the Step method and put its expression in the loop; compare both configurations again.
  2. Add a Condition on the configuration to the csproj that sets Optimize to true in Debug and measure the result.
  3. Print #if DEBUG in both configurations and compare the output.
  4. Run the Release build under DOTNET_TieredCompilation=0 and compare the median.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does dotnet run -c Release change?

    Answer

    It builds the optimized configuration and runs it

    The configuration is a build setting, chosen with -c.

  2. Which configuration does a plain dotnet run use?

    Answer

    Debug

    Debug is the default, which is why benchmarks name Release explicitly.

  3. What did the medians show on this machine?

    Answer

    Debug 714.83 ms and Release 245.09 ms

    The tables on the page are the two runs of the same program.

  4. What stayed the same in both configurations?

    Answer

    The total the loop computed

    Both printed 149999997, which is the correctness check of the comparison.

  5. With dotnet run -c Release, which branch of #if DEBUG / #else is compiled?

    Answer

    The #else branch

    Release does not define DEBUG, so the #if block is not part of the program.

  6. What defines the DEBUG symbol?

    Answer

    The SDK for the Debug configuration

    The project sets DefineConstants per configuration, and Debug includes DEBUG.

  7. Why should a published number come from a Release build?

    Answer

    The optimizer changes the code that runs

    The measured difference was nearly a factor of three.

  8. What does this program print? #if DEBUG Console.WriteLine("debug"); #else Console.WriteLine("release"); #endif run as dotnet run

    Answer

    debug

    The default configuration defines DEBUG.

  9. What is the risk of a check inside #if DEBUG?

    Answer

    The check is absent in the build a user runs

    A validation of user input must not depend on the configuration.

  10. Does a Release build change the result of correct code?

    Answer

    No, an optimization must preserve the answer

    Both configurations printed the same total on the page.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev