skip to content

In C#, what does [Conditional("DEBUG")] on a logging method remove from a Release build, and whose build symbols decide it?

level: middleimportance: should knowfreq 30%

answer

  1. the call disappears, not the method
  2. arguments go with it
  3. the caller's compilation symbols
  4. void, no out parameters

basics

~20 s

[Conditional("DEBUG")] makes the compiler drop every call to the method, including evaluation of its arguments, when the calling code is compiled without DEBUG. The method itself stays in the assembly, and the caller's symbols decide.

solid answer

~40 s

`System.Diagnostics.ConditionalAttribute` is acted on by the C# compiler at each **call site**: if the conditional symbol, such as `DEBUG`, is not defined in the compilation that contains the call, the compiler emits nothing for the call, so argument expressions like `Dump(BuildSnapshot())` are not evaluated either. The method's body is still compiled into its assembly, which is why a library built in Release still serves Debug callers: the consumer's symbols decide. The method must return `void` (CS0578), cannot have `out` parameters, and cannot be an override or an interface member; several `[Conditional]` attributes combine with OR. Unlike `#if DEBUG` around a block, nothing disappears from the declaring file. Applied to an attribute class, it controls whether the attribute is emitted into metadata.

code

csharp · 20 lines
csharp
using System.Diagnostics;

int calls = 0;
string Expensive() { calls++; return "snapshot"; }

Diag.Dump(Expensive());
Diag.Always(Expensive());
Console.WriteLine($"Expensive() ran {calls} time(s)");
#if DEBUG
Console.WriteLine("DEBUG defined");
#else
Console.WriteLine("DEBUG not defined");
#endif

static class Diag
{
    [Conditional("DEBUG")]
    public static void Dump(string state) => Console.WriteLine($"dump: {state}");
    public static void Always(string state) => Console.WriteLine($"always: {state}");
}

go deeper

for a junior

Recall that Debug.WriteLine and Debug.Assert disappear in Release builds because of [Conditional("DEBUG")], and that the method must return void.

for a middle

Explain that the call and its argument evaluation are removed at compile time, that the caller's symbols decide, and how it differs from #if around the method.

for a senior

Use it to make expensive diagnostics free in production, know the CS0578 and override restrictions, and explain why a Release-built library still serves Debug consumers.

for a principal

Separate compile-time removal from run-time log levels in team guidance, so production behaviour never silently depends on whether a call site was compiled in Debug.

## What the compiler does with [Conditional] `[Conditional("DEBUG")]` (the class is `System.Diagnostics.ConditionalAttribute`) is one of the attributes the C# compiler interprets itself. It is not read at run time. When the compiler binds a call to a conditional method, it checks whether the named **conditional compilation symbol** is defined in the compilation it is building: - **Defined**: the call is compiled normally. - **Not defined**: the entire call expression is omitted from the IL, **including the evaluation of its arguments**. That second point is the practical reason to use it. In the snippet below, `Expensive()` runs twice in Debug and once in Release, because in Release the `Diag.Dump(Expensive())` statement vanishes with its argument. ```csharp [Conditional("DEBUG")] public static void Dump(string state) => Console.WriteLine($"dump: {state}"); Diag.Dump(Expensive()); // Release: nothing is emitted, Expensive() never runs ``` The .NET SDK defines `DEBUG` in the default Debug configuration and not in Release; `TRACE` is added to `DefineConstants` for every configuration by the C# SDK props. The BCL's `Debug.WriteLine` and `Debug.Assert` are declared `[Conditional("DEBUG")]`, which is why those calls cost nothing in Release builds. ## Whose symbols count The decision is made where the **call** is compiled, not where the method is declared. A library compiled in Release still contains the full body of its `[Conditional("DEBUG")]` method. An application built in Debug that calls it gets the call; the same application built in Release does not. This is the key difference from `#if`: | | `[Conditional("DEBUG")]` | `#if DEBUG ... #endif` | |---|---|---| | What is removed | each call site, with its argument evaluation | the enclosed source text itself | | Method body | always compiled into the declaring assembly | removed if it sits inside the block | | Decided by | symbols of the calling compilation | symbols of the file being compiled | | Callers when symbol is off | compile fine, call omitted | break if they reference a removed member | ## Rules the compiler enforces Because a call might not exist, the method cannot produce anything a caller could depend on. The SDK compiler reports: 1. **CS0578**, "The Conditional attribute is not valid on 'Bad.Count()' because its return type is not void", for a non-void method. 2. **CS0685**, for a conditional method with an `out` parameter. 3. **CS0243**, for an `override` method; mark the base declaration instead, since a call to a virtual method binds to that declaration. 4. **CS0582**, on interface members. 5. **CS1618**, when you try to create a delegate from a conditional method. `[Conditional]` can also be applied to an **attribute class** (anything else is CS1689). Then uses of that attribute are only emitted into metadata when the symbol is defined at the use site, which suits diagnostic markers you want only in Debug builds. ## Several conditions A method may carry more than one `[Conditional]`; the call is kept if **any** of the symbols is defined. `[Conditional("DEBUG")] [Conditional("TRACE_ON")]` keeps the call in a Debug build and in a Release build that defines `TRACE_ON`. ## Walking through the example In the snippet, `Diag.Dump(Expensive())` and `Diag.Always(Expensive())` each pass the result of `Expensive()`, which increments a counter. - **Debug** (`dotnet run q4.cs`): `DEBUG` is defined, both calls are compiled, the output shows `dump: snapshot` and `always: snapshot`, and the counter reads 2. - **Release** (`dotnet run q4.cs -c Release`): the compiler omits the `Dump` statement entirely, so only `always: snapshot` prints and the counter reads 1, proving the argument was never evaluated. The same experiment across two projects settles the "whose symbols" question: a class library built with `-c Release` that declares `[Conditional("DEBUG")] Dump`, referenced by a console app, prints the dump when the app is built in Debug and stays silent when the app is built in Release. Nothing about the library changed between those runs; only the caller's compilation symbols did. ## When to reach for it - Debug-only diagnostics whose arguments are expensive: state dumps, invariant checks, verbose logging that should cost nothing in production. - Library helpers that consumers should be able to switch on in their own Debug builds. - Not for behaviour that production relies on: if code needs the result, it cannot be conditional, which is exactly why the compiler insists on `void`. Production logging that must be switchable at run time belongs to a logging framework's level checks, not to compile-time removal.

  • Why must a [Conditional] method return void?
    Because the call may not exist in the caller's build. If `Count()` returned an `int`, an expression like `var n = Count();` would have no value when the call is removed. The compiler therefore rejects non-void conditional methods with CS0578, and also rejects `out` parameters, which are another way of producing a value.
  • A NuGet library is built in Release and has a [Conditional("DEBUG")] Dump method. Does a consumer's Debug build call it?
    Yes. The conditional check happens when the consumer's code is compiled, against the consumer's symbols. The library's Release build kept the method body; only calls compiled without `DEBUG` are omitted. That is the design difference from wrapping the method in `#if DEBUG`, which would remove it from the library entirely.

It is like a scene marked rehearsal-only in a script: each production decides whether to stage it, and when a production cuts it, the props that scene needs are never even brought on stage.

  • Thinks the method body is stripped and its arguments still evaluated
  • Believes the library's own build configuration decides whether calls run
  • Treats [Conditional] as a run-time check of the build configuration
  • Puts [Conditional] on a method that returns a value
  • Thinks several [Conditional] attributes require all symbols to be defined