Conditional Attribute

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Syntax and Invocation

// --- Callee Context (e.g., Library.cs) 
using System.Diagnostics;

public class ConditionalExample
{
    // The method definition is always compiled into the assembly's IL.
    [Conditional("FEATURE_X")]
    public static void ExecuteFeature(int value)
    {
        // Method implementation
    }
}

// --- Caller Context (e.g., Program.cs) 
#define FEATURE_X // Preprocessor symbol defined in the caller's context

public class Program
{
    public static void Main()
    {
        // Because FEATURE_X is defined in this context, the compiler emits this call.
        // If #define FEATURE_X is removed, the compiler strips this invocation entirely.
        ConditionalExample.ExecuteFeature(42); 
    }
}

​

Compilation Mechanics

• Caller Context Evaluation: Because the symbol is evaluated at the call site, a library can compile a [Conditional] method into its assembly permanently, while the decision to emit invocations is dictated entirely by the consuming application’s build configuration. This is a primary distinction from #if / #endif directives, which physically exclude code based on the assembly’s own compilation context.
• Call-Site Omission: The compiler removes the invocation at the call site but does not remove the method declaration from the defining assembly.
• Argument Evaluation: If the method call is omitted, any expressions passed as arguments to that method are not evaluated. This prevents unintended side effects from executing when the method call is stripped.
• Logical OR Evaluation: Applying multiple [Conditional] attributes to a single method results in a logical OR operation. If any of the specified symbols are defined in the caller’s context, the method calls are included in the compilation.

[Conditional("ALPHA")]
[Conditional("BETA")]
public void Execute() { } // Call is emitted if ALPHA OR BETA is defined by the caller

​

Structural Constraints

1. Return Type: The target method must have a void return type. Methods returning a value cannot be conditional because the compiler cannot guarantee a return value at the call site if the invocation is omitted.
2. Parameter Restrictions: The method cannot contain out parameters. If the method call is omitted, the out parameter would remain unassigned, violating C# definite assignment rules. ref parameters are permitted.
3. Member Types: It can only be applied to methods or attribute classes. It cannot be applied to properties, fields, events, or constructors.
4. Abstract Methods: The method cannot be marked as abstract.
5. Entry Point: The method cannot be the entry point of an application (e.g., Main).
6. Interface Implementations: It cannot be applied to an interface method declaration or to a method that implements an interface.
7. Overrides: If a virtual method is marked with [Conditional], any overridden implementations in derived classes are implicitly conditional and cannot explicitly declare the [Conditional] attribute.
8. Delegates: You cannot create a delegate pointing to a conditional method, as the compiler cannot conditionally omit delegate invocations.

​

Application to Attribute Classes

#define INCLUDE_METADATA // Must precede all other tokens in the file

using System;
using System.Diagnostics;

// --- Attribute Definition 
[Conditional("INCLUDE_METADATA")]
[AttributeUsage(AttributeTargets.Class)]
public class CustomTrackingAttribute : Attribute { }

// --- Attribute Application 
[CustomTracking] // Emitted into IL metadata only because INCLUDE_METADATA is defined
public class TargetClass { }