What is the difference between Debug and Release builds in .NET, and why can code behave differently between them?

1. A configuration is just a set of properties

Debug and Release are names. The SDK attaches default property values to each, and -c Release simply sets the global property Configuration=Release.

The RELEASE symbol comes from the SDK's implicit configuration define: it adds the configuration name in upper case, so a custom Profiling configuration gets PROFILING. DisableImplicitConfigurationDefines=true turns that off. Target framework symbols (NET, NET10_0, NET10_0_OR_GREATER) are defined in both.

Check the real values for your project rather than trusting memory:

dotnet msbuild -getProperty:Optimize -getProperty:DefineConstants -getProperty:DebugType -p:Configuration=Release

2. Where the differences come from

               C# source
                   |
        +----------+-----------+
        | Debug                | Release
        v                      v
  csc /optimize-          csc /optimize+
  /define:DEBUG;TRACE     /define:RELEASE;TRACE
  extra nops for          #if DEBUG code removed
  breakpoints, locals     Debug.Assert(...) calls removed,
  kept for the debugger   including their arguments
        |                      |
   IL + portable PDB      IL + portable PDB
   [Debuggable(DisableOptimizations)]
        |                      |
        v                      v
  JIT: minimal opts       JIT: tiered compilation (tier 0 -> tier 1),
  locals live to end      inlining, loop hoisting, dynamic PGO,
  of method               shorter object lifetimes

Two separate layers optimise: the C# compiler (modestly) and the JIT (much more). Most behaviour differences come from the JIT, which is why a Release build run under a debugger that suppresses JIT optimisation can hide the bug you're chasing.

3. Four reasons behaviour differs

The second-order effect matters too: [Conditional] is decided by the caller's compilation symbols. NuGet packages are built in Release, so their Debug.Assert calls never run in your app, whichever configuration you build.

4. Build configuration is not the environment

A Release binary can run as Development, and a Debug binary can run as Production. Use the environment (and configuration providers such as environment variables, Key Vault or Azure App Configuration) for anything that differs between staging and production; use build configurations only for genuinely different builds.

5. Defaults per command

The mismatch is the trap: a pipeline that runs dotnet test without -c Release and then dotnet publish tests one program and ships another.

6. Debugging Release builds

• Release PDBs give file names and line numbers in stack traces and dumps; keep them (artefact store or symbol server).
• Stepping can jump, some locals show as "optimised away", and inlined methods have no frame of their own.
• Visual Studio's "Suppress JIT optimization on module load" makes Release debuggable but also hides JIT-caused bugs, so turn it off when chasing a Release-only problem.
• For Release-only bugs, prefer logging, dotnet-dump dumps from the real environment, and small reproductions run with -c Release.

7. Custom configurations

<PropertyGroup>
  <Configurations>Debug;Release;Profiling</Configurations>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)' == 'Profiling'">
  <Optimize>true</Optimize>
  <DebugType>portable</DebugType>
</PropertyGroup>

A custom configuration starts with no SDK defaults beyond the general ones, so set Optimize and anything else explicitly. Good uses: an instrumented build for profiling, or a build with extra diagnostics for a specific investigation. Bad uses: Staging and Production, which create different binaries per environment.

8. Performance

• Debug code can be several times slower than Release for CPU-bound work, so Debug benchmarks are meaningless. BenchmarkDotNet refuses to run (or warns) on non-optimised builds.
• Release startup also benefits from tiered compilation and, if you publish with it, ReadyToRun.
• Load tests, profiling and performance baselines should always use the same Release artefact you deploy.

9. Security

• Never guard authentication, authorisation or data handling with #if DEBUG / #if !DEBUG; one wrong flag ships the bypass.
• Don't leave secrets or test credentials inside #if DEBUG blocks; they're still in source control, and a Debug build can end up deployed.
• Developer-only behaviour belongs behind the environment check (app.Environment.IsDevelopment()), which is visible in configuration and easier to audit.

10. .NET 11 awareness

The configuration model is stable. The JIT gets more aggressive with each release (inlining, PGO, escape analysis), which can expose new Release-only bugs in code that relied on undefined behaviour. Re-run your Release test suite when you trial .NET 11, and keep production on .NET 10 until you've done so.

11. Try it yourself

1. Run the code example with dotnet run, then with dotnet run -c Release.
2. Compare: the #if DEBUG line changes and "Side effects ran" drops from 1 to 0.
3. Let the timer loop run for 30 seconds in both configurations and compare the tick counts; then uncomment GC.KeepAlive(timer) and repeat.
4. Run dotnet msbuild -getProperty:DefineConstants -p:Configuration=Release and look for RELEASE.
5. Add a Profiling configuration, build with -c Profiling, and check Optimize and DefineConstants.
6. Open the Debug and Release DLLs in ILSpy and compare the IL of the same method.
7. Run the Release build as DOTNET_ENVIRONMENT=Development to see that configuration and environment are independent.

using System.Diagnostics;

namespace ConfigDemo;

internal static class Program
{
    private static int _sideEffects;

    private static void Main()
    {
#if DEBUG
        Console.WriteLine("Built in Debug");
#else
        Console.WriteLine("Built in Release");
#endif

        // In Release the whole call, including CountCall(), is removed
        Debug.Assert(CountCall() > 0, "never shown in Release");
        Console.WriteLine($"Side effects ran: {_sideEffects}");

        // A timer only referenced by a local can be collected in Release
        var ticks = 0;
        var timer = new Timer(_ => Interlocked.Increment(ref ticks), null, 0, 100);
        for (var i = 0; i < 30; i++)
        {
            Thread.Sleep(1000);
            GC.Collect();
            Console.WriteLine($"ticks: {Volatile.Read(ref ticks)}");
        }
        // Uncomment to keep the timer alive in every configuration:
        // GC.KeepAlive(timer);
    }

    private static int CountCall() => ++_sideEffects;
}

dotnet run            # Debug: "Side effects ran: 1", ticks keep rising
dotnet run -c Release # Release: "Side effects ran: 0", ticks may stop after a GC