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:
- dotnet run builds and runs Debug, which is what a development loop wants.
- dotnet run -c Release builds and runs the optimized configuration, which every number published to a user should come from.
- dotnet build -c Release and dotnet publish -c Release have the same switch; the lesson on publishing uses it.
- A project may set properties per configuration in the csproj with a Condition on '$(Configuration)' == 'Release'.
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
| Configuration | Min ms | Median ms | Total |
|---|---|---|---|
| Debug | 563.57 | 714.83 | 149 999 997 |
| Release | 242.52 | 245.09 | 149 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
- Remove the Step method and put its expression in the loop; compare both configurations again.
- Add a Condition on the configuration to the csproj that sets Optimize to true in Debug and measure the result.
- Print #if DEBUG in both configurations and compare the output.
- 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.
-
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.
-
Which configuration does a plain dotnet run use?
Answer
Debug
Debug is the default, which is why benchmarks name Release explicitly.
-
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.
-
What stayed the same in both configurations?
Answer
The total the loop computed
Both printed 149999997, which is the correctness check of the comparison.
-
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.
-
What defines the DEBUG symbol?
Answer
The SDK for the Debug configuration
The project sets DefineConstants per configuration, and Debug includes DEBUG.
-
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.
-
What does this program print?
#if DEBUG Console.WriteLine("debug"); #else Console.WriteLine("release"); #endifrun asdotnet runAnswer
debug
The default configuration defines DEBUG.
-
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.
-
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