How does conditional compilation work in C#, and when should you use #if, DefineConstants or the [Conditional] attribute instead of run-time configuration?

1. When each decision is made

  Project file                     Compile time (csc)                     Publish time (trimmer/AOT)       Run time
  ------------------------         --------------------------------       ---------------------------      -----------------------
  DefineConstants = TRACE;X        #if X -> code included or not          feature switches can remove      IConfiguration, env vars
  TargetFramework = net10.0  --->  NET10_0_OR_GREATER defined       --->  guarded code when the switch --->  feature flags
  Configuration  = Release         [Conditional("DEBUG")] calls           is a constant                    OperatingSystem.IsWindows()
                                   removed at the CALL SITE

  different symbols => different IL => a different program to build and test

The further right a decision is made, the fewer binaries you have to build and test. Prefer run time unless you have a reason not to.

2. The directives

Expressions support &&, ||, !, ==, != and parentheses:

#if NET10_0_OR_GREATER && !BROWSER
    // .NET 10+, not WebAssembly
#endif

Code in an inactive branch isn't compiled at all, so it can use APIs that don't exist for that target, but it also isn't checked by the compiler or analysers.

3. Where symbols come from

Check what the compiler actually receives:

dotnet msbuild -getProperty:DefineConstants -p:Configuration=Release -p:TargetFramework=net10.0

Why appending matters, and the command-line trap

<!-- Replaces DEBUG, TRACE and every TFM symbol -->
<DefineConstants>ENABLE_X</DefineConstants>

<!-- Correct -->
<DefineConstants>$(DefineConstants);ENABLE_X</DefineConstants>

-p:DefineConstants=ENABLE_X on the command line is a global property: it overrides every assignment in the project and SDK, so all the implicit symbols disappear for that build. If you must add a symbol from CI, define your own property (for example -p:EnableX=true) and append the symbol conditionally in the project.

4. The [Conditional] attribute in depth

[Conditional("DEBUG")]
public static void Dump(Order order) => Console.WriteLine(order);

// caller
Diagnostics.Dump(LoadOrder());   // in a caller built without DEBUG: no call, and LoadOrder() never runs

Debug.* methods are [Conditional("DEBUG")]; Trace.* methods are [Conditional("TRACE")], which is why tracing still works in Release.

5. Choosing the right tool

6. Organising platform and framework code

When #if blocks grow, move the differences out of method bodies:

Clock.cs              public partial class Clock { public partial DateTimeOffset Now(); }  (shared)
Clock.net10.cs        partial implementation using TimeProvider (included for net10.0)
Clock.netstandard.cs  partial implementation for netstandard2.0

<ItemGroup Condition="'$(TargetFramework)' != 'netstandard2.0'">
  <Compile Remove="**/*.netstandard.cs" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
  <Compile Remove="**/*.net10.cs" />
</ItemGroup>

Each file then reads as normal code, and reviewers see platform differences in one place.

7. Testing every combination

• Two TFMs times Debug and Release is already four different programs.
• Multi-targeted projects build every TFM by default; make sure the test projects multi-target too, so tests run for each one.
• Add an OS matrix in CI where OS symbols or OS-specific TFMs are used.
• Analysers and refactorings only see active branches. In the IDE, switch the target framework picker to check the other branches.

8. Performance

• Conditional compilation has no run-time cost: removed code doesn't exist.
• Run-time checks such as OperatingSystem.IsWindows() are JIT intrinsics and fold to constants, so they cost essentially nothing either. That removes the main performance argument for #if.
• Feature switches let the trimmer remove whole subsystems at publish time, which matters for AOT and mobile apps.

9. Security

• Never make authentication, signature validation or authorisation depend on a compile-time symbol. A pipeline change can ship the wrong variant, and reviewers can't see which variant was deployed.
• Use configuration (sandbox keys, test tenants) for non-production differences, so the security code path is identical everywhere.
• Don't hide secrets in #if DEBUG blocks; they're still in source control and in any Debug build that escapes.

10. .NET 11 awareness

Each new framework adds its own symbols (NET11_0, NET11_0_OR_GREATER) automatically when you add the TFM. Avoid adding #if NET11_0_OR_GREATER code to production libraries until .NET 11 is released and you actually ship that target. Keep production on net10.0 until then.

11. Try it yourself

1. Add <DefineConstants>$(DefineConstants);ENABLE_TELEMETRY</DefineConstants> and an #if ENABLE_TELEMETRY block; build Debug and Release and print DefineConstants for each.
2. Change it to <DefineConstants>ENABLE_TELEMETRY</DefineConstants> and watch #if DEBUG stop working.
3. Build with -p:DefineConstants=ENABLE_TELEMETRY and check which symbols survive.
4. Add a [Conditional("DEBUG")] method called with LoadOrder() as its argument, log inside LoadOrder, and run in Release.
5. Put the conditional method in a class library built in Release and call it from a Debug console app. Does it run?
6. Multi-target net8.0;net10.0, use #if NET10_0_OR_GREATER, and switch the IDE's framework picker to see the other branch light up.
7. Replace an #if WINDOWS block with OperatingSystem.IsWindows() and [SupportedOSPlatform("windows")], and see what CA1416 reports when the guard is missing.

<PropertyGroup>
  <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
  <!-- Append: keep DEBUG/TRACE and TFM symbols -->
  <DefineConstants>$(DefineConstants);ENABLE_DIAGNOSTIC_DUMPS</DefineConstants>
</PropertyGroup>

using System.Diagnostics;

namespace Orders.Domain;

public sealed record Order(Guid Id, decimal TotalInclGst);

public static class Diagnostics
{
    // Calls disappear from callers compiled without DEBUG
    [Conditional("DEBUG")]
    public static void Dump(Order order) => Console.WriteLine($"[debug] {order}");
}

public sealed class OrderLock
{
#if NET10_0_OR_GREATER
    private readonly Lock _gate = new();
#else
    private readonly object _gate = new();
#endif

    public void Run(Action action)
    {
        lock (_gate)
        {
            action();
        }
    }
}

public sealed class PaymentCallbackValidator(IConfiguration configuration)
{
    // Environment differences come from configuration, never from #if
    private readonly string _signingKey = configuration["Payments:SigningKey"]
        ?? throw new InvalidOperationException("Payments:SigningKey is not configured.");

    public bool IsValid(string payload, string signature) =>
        CryptographicOperations.FixedTimeEquals(
            Convert.FromHexString(signature),
            HMACSHA256.HashData(Encoding.UTF8.GetBytes(_signingKey), Encoding.UTF8.GetBytes(payload)));
}

The validator assumes using System.Security.Cryptography;, using System.Text; and using Microsoft.Extensions.Configuration;.