Using the Conditional Attribute in C#

The great thing about these methods is that they only run when the application is compiled in Debug mode. If the application is compiled in Release mode, these calls seem to vanish from the code altogether. This allows developers to freely add helpful debug messages and assertions during development without worrying about the impact on the release version of their application.

But how exactly does this work behind the scenes? It turns out that these debug method calls are removed from the final code when compiling in Release mode. This process is done through a special method attribute, called the ConditionalAttribute, and it’s not exclusive to Microsoft's code.

The Conditional Attribute

For example:

[Conditional("DEBUG")]
public static void WriteLine(string message)

The Conditional("DEBUG") attribute tells the compiler to only include the method in the compiled code if the DEBUG symbol is defined. In other words, the call to WriteLine is stripped out when the application is compiled in Release mode because the DEBUG symbol is not defined by default in that build configuration.

namespace ConditionalAttributeTest
{
  class Program
  {
    static void Main(string[] args)
    {
      Debug.WriteLine("I'm a message!");
    }
  }
}

When compiled in Debug mode, the MSIL (Microsoft Intermediate Language) of the application will contain a call to Debug.WriteLine that outputs the message. However, if the same code is compiled in Release mode, you won’t find any trace of the WriteLine call in the MSIL

In Debug mode (MSIL output):

.method private hidebysig static void Main(string[] args) cil managed
{
    .entrypoint
    .maxstack 8
    L_0000: nop 
    L_0001: ldstr "I'm a message!"
    L_0006: call void [System]System.Diagnostics.Debug::WriteLine(string)
    L_000b: nop 
    L_000c: ret 
}

In Release mode (MSIL output):

.method private hidebysig static void Main(string[] args) cil managed
{
    .entrypoint
    .maxstack 8
    L_0000: ret 
}

As you can see, in Release mode, the WriteLine call is entirely removed, including the string argument. This is how the Conditional attribute works to ensure that debug-only code doesn’t impact performance in the release version of the application.

Using the Conditional Attribute with Custom Symbols

You can also define your own symbols to conditionally compile methods.

For example, let’s say you want to track performance using timers, but only include the related code when the TIMERS symbol is defined.

public static class TimerCalls
{
  private static Dictionary<string, Stopwatch> _Stopwatches = new Dictionary<string, Stopwatch>();

  [Conditional("TIMERS")]
  public static void Start(string key)
  {
    if (_Stopwatches.ContainsKey(key)) return; // Stopwatch already running
    _Stopwatches.Add(key, Stopwatch.StartNew());
  }

  [Conditional("TIMERS")]
  public static void Stop(string key)
  {
    if (!_Stopwatches.ContainsKey(key)) return; // No such stopwatch currently
    var watch = _Stopwatches[key];
    watch.Stop();
    _Stopwatches.Remove(key);
    Console.WriteLine($"Timer: {key}, {watch.Elapsed.TotalMilliseconds}ms");
  }
}

Now, if you define TIMERS at the top of your code:

#define TIMERS

class Program
{
  static void Main(string[] args)
  {
    TimerCalls.Start("SumNumbers");
    int total = 0;
    for (int i = 0; i < 10000; i++) { total += i; }
    Console.WriteLine(total);
    TimerCalls.Stop("SumNumbers");
    Console.Read();
  }
}

The output would look something like this:

49995000
Timer: SumNumbers, 2.7013ms

However, if you remove the #define TIMERS statement, the timer-related methods (Start and Stop) will be excluded from the compiled code entirely, and the output will be:

49995000

Why Use the Conditional Attribute?

While you could use preprocessor directives like #if and #endif to achieve similar results, using the ConditionalAttribute has some key advantages. For one, it reduces clutter in your code, making it easier to read and maintain. Instead of surrounding every debug call with conditional compilation blocks, the ConditionalAttribute automatically handles the inclusion or removal of methods based on the defined symbols.

The ConditionalAttribute is a powerful and convenient feature in C# that allows developers to include or exclude method calls based on compilation settings or custom-defined symbols. It simplifies debugging and performance monitoring during development, and ensures that unnecessary code doesn’t end up in the release version of your application.