C# Attributes — The Reflection Caching Gap Killing Your RPS

Every production .NET codebase is full of attributes — [Serializable], [HttpGet], [Required], [Authorize] — and yet most junior developers treat them like magic spells they copy from Stack Overflow without understanding what's actually happening. That's a problem, because attributes are one of the most powerful tools in C# for writing clean, self-documenting, and extensible code without littering your business logic with repetitive boilerplate.

Attributes solve a specific problem: how do you attach extra information to a piece of code — a method, a class, a property — without changing its logic or signature? Before attributes, you'd need conventions, separate config files, or mountains of if-statements. Attributes let you declare intent right next to the code it describes, and then read that intent at runtime using reflection or at compile time using Roslyn analyzers.

By the end you'll understand exactly what attributes are and how the CLR handles them, how to read them at runtime using reflection, how to write your own custom attributes for real use cases like validation or logging, and the gotchas that trip up even experienced developers. You'll go from copy-pasting [JsonIgnore] to knowing precisely why it does what it does.

What Attributes Actually Are Under the Hood

An attribute in C# is just a class that inherits from System.Attribute. That's it. When the C# compiler sees [Obsolete("Use NewMethod instead")] above your method, it doesn't generate any runtime code at that call site — it embeds metadata into the compiled assembly's IL (Intermediate Language). The attribute instance doesn't even get created until something asks for it via reflection.

This is the key insight most developers miss: attributes are lazy. They cost nothing at runtime unless you read them. The compiled assembly carries the attribute data around like a passport stamp — it's there if anyone checks, but it doesn't slow you down at the border unless the border agent actually looks.

The square-bracket syntax [AttributeName] is just compiler sugar. Writing [Obsolete] is identical to writing [ObsoleteAttribute] — the compiler strips the 'Attribute' suffix automatically when resolving names. And you can pass arguments to the attribute's constructor or set its public properties using named parameters inside the brackets.

Attributes can target specific language elements: classes, methods, properties, fields, parameters, assemblies, and more. You control this with the [AttributeUsage] attribute on your custom attribute class — which is wonderfully meta.

using System;
using System.Reflection;

// A plain old class decorated with a built-in attribute.
// [Serializable] tells the runtime this class can be converted
// to bytes (e.g., for file storage or network transfer).
[Serializable]
public class CustomerOrder
{
    public int OrderId { get; set; }

    // [Obsolete] is a compiler-level attribute.
    // The string is the message shown in IDE warnings and build output.
    [Obsolete("Use CalculateTotalWithTax() instead. This method ignores VAT.")]
    public decimal CalculateTotal()
    {
        return 99.99m;
    }

    public decimal CalculateTotalWithTax(decimal vatRate)
    {
        return 99.99m * (1 + vatRate);
    }
}

class Program
{
    static void Main()
    {
        var order = new CustomerOrder { OrderId = 42 };

        // Reflect on the CustomerOrder TYPE (not an instance).
        // GetType() returns a Type object — the runtime's description
        // of what CustomerOrder looks like.
        Type orderType = order.GetType();

        // Check whether [Serializable] is present on this class.
        // IsDefined() is the fast path — it doesn't instantiate the attribute,
        // just checks if the metadata token exists.
        bool isSerializable = orderType.IsDefined(typeof(SerializableAttribute), inherit: false);
        Console.WriteLine($"Is CustomerOrder serializable? {isSerializable}");

        // Now look at a specific method and read its ObsoleteAttribute.
        MethodInfo oldMethod = orderType.GetMethod("CalculateTotal")!;

        // GetCustomAttribute<T>() DOES instantiate the attribute object.
        // This is the moment the attribute's constructor runs.
        ObsoleteAttribute? obsoleteInfo =
            oldMethod.GetCustomAttribute<ObsoleteAttribute>();

        if (obsoleteInfo != null)
        {
            // The Message property is set in the attribute's constructor.
            Console.WriteLine($"Warning — method is obsolete: {obsoleteInfo.Message}");
        }
    }
}

Attribute Targets, AllowMultiple, and Inheritance — The Rules That Bite You

Once you start writing custom attributes, three settings in [AttributeUsage] determine everything: AttributeTargets, AllowMultiple, and Inherited. Getting these wrong is the most common source of confusing bugs.

AttributeTargets is a flags enum, so you can combine targets with the bitwise OR operator: AttributeTargets.Class | AttributeTargets.Method means the attribute is valid on both classes and methods. Use AttributeTargets.All if it genuinely makes sense everywhere, but be conservative — narrow targeting helps other developers avoid misusing your attribute.

AllowMultiple = true means you can stack the same attribute multiple times on one member. This is useful for things like [InlineData(1), InlineData(2)] in xUnit where each instance carries different test data. When AllowMultiple is false (the default) and you accidentally apply the same attribute twice, you get a compile error — which is actually the safe, desirable outcome.

Inherited = true means if ClassA has your attribute and ClassB inherits from ClassA, calling GetCustomAttribute on ClassB will also return the attribute. This is the default and usually what you want. Set it to false when the attribute is specifically about the declaring class, not its descendants — for example, a [DatabaseTable("customers")] attribute mapping a class to a DB table name shouldn't silently inherit to subclasses that might map to different tables.

using System;
using System.Reflection;

// This attribute can go on a class OR a method — not a property or field.
// AllowMultiple = true so we can attach multiple tags to one method.
// Inherited = false — subclasses don't silently inherit ownership tags.
[AttributeUsage(
    AttributeTargets.Class | AttributeTargets.Method,
    AllowMultiple = true,
    Inherited = false
)]
public sealed class OwnedByTeamAttribute : Attribute
{
    public string TeamName { get; }
    public string SlackChannel { get; set; } = "#engineering";

    public OwnedByTeamAttribute(string teamName)
    {
        TeamName = teamName;
    }
}

// Two attributes on the same class — allowed because AllowMultiple = true.
[OwnedByTeam("Payments", SlackChannel = "#payments-team")]
[OwnedByTeam("Platform", SlackChannel = "#platform-infra")]
public class RefundProcessor
{
    // A single attribute on a method.
    [OwnedByTeam("Payments")]
    public void IssueRefund(string orderId, decimal amount)
    {
        Console.WriteLine($"Refund of £{amount} issued for order {orderId}");
    }

    public void LogRefundAttempt(string orderId)
    {
        Console.WriteLine($"Logging refund attempt for {orderId}");
    }
}

// Subclass — does NOT inherit the [OwnedByTeam] attributes
// because Inherited = false on the attribute definition.
public class PartialRefundProcessor : RefundProcessor { }

class Program
{
    static void Main()
    {
        Type processorType = typeof(RefundProcessor);

        // GetCustomAttributes returns ALL instances when AllowMultiple = true.
        OwnedByTeamAttribute[] classOwners =
            (OwnedByTeamAttribute[])processorType
                .GetCustomAttributes(typeof(OwnedByTeamAttribute), inherit: false);

        Console.WriteLine("=== RefundProcessor owners ===");
        foreach (var owner in classOwners)
        {
            Console.WriteLine($"  Team: {owner.TeamName} | Channel: {owner.SlackChannel}");
        }

        // Now check the subclass — should have ZERO owners because Inherited = false.
        Type subType = typeof(PartialRefundProcessor);
        OwnedByTeamAttribute[] subOwners =
            (OwnedByTeamAttribute[])subType
                .GetCustomAttributes(typeof(OwnedByTeamAttribute), inherit: false);

        Console.WriteLine($"\n=== PartialRefundProcessor owners (expect 0): {subOwners.Length} ===");

        // Check the method — one attribute, attached at method level.
        MethodInfo issueRefundMethod = processorType.GetMethod("IssueRefund")!;
        OwnedByTeamAttribute[] methodOwners =
            (OwnedByTeamAttribute[])issueRefundMethod
                .GetCustomAttributes(typeof(OwnedByTeamAttribute), inherit: false);

        Console.WriteLine("\n=== IssueRefund method owners ===");
        foreach (var owner in methodOwners)
        {
            Console.WriteLine($"  Team: {owner.TeamName}");
        }
    }
}

Attribute Targets Quick-Reference Table

The AttributeTargets enum defines every code element you can decorate with an attribute. You combine them with bitwise OR (|) in [AttributeUsage]. Below is the complete list of values, each with a description and an example of when you'd use it.

When designing your own attribute, be as specific as possible. For example, if your attribute only makes sense on methods, use AttributeTargets.Method — not All. This gives compile-time validation and makes intent clear.

using System;

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method | AttributeTargets.Property)]
public class SensitiveDataAttribute : Attribute { }

[SensitiveData] // on class is valid
public class UserCredentials
{
    [SensitiveData] // on property is valid
    public string Password { get; set; } = string.Empty;

    // Compile error: Attribute 'SensitiveDataAttribute' is not valid on this declaration type.
    // [SensitiveData]
    // public void Encrypt() { }

    // This would work if we added AttributeTargets.Method above.
}

Visual Reflection Pipeline: How Attributes Are Read and Cached

The pipeline is straightforward but the performance cliff is hidden in the 'No' branch. Each 'No' costs a constructor invocation, property assignment, and heap allocation. At 10,000 RPS, even a 1-microsecond instantiation adds 10ms of CPU time per second — pinning a core at 100%.

The diagram shows the key enabler: a ConcurrentDictionary<MethodInfo, T> sitting between the reflection call and the business logic. The first request suffers the allocation cost; all subsequent requests pay only the dictionary lookup (nanoseconds). For ultra-hot paths, source generators (Roslyn) skip the entire pipeline by generating attribute access code at compile time — the attribute data is baked into static fields, eliminating both reflection and caching.

Attributes and Conditional Compilation — The #if (DEBUG) Pattern

Attributes are metadata attached at compile time, but their presence can be controlled by conditional compilation symbols like DEBUG, RELEASE, or custom symbols. This is useful when you want attribute-driven behaviour only in certain build configurations without modifying the source code.

There are two mechanisms: one is the [Conditional] attribute from System.Diagnostics — it marks a method so that calls to it (including attribute instantiation if the attribute's code uses it) are omitted unless the specified symbol is defined. However, [Conditional] on an attribute class itself only works if the attribute's constructor or property setters are called — but attribute instantiation via reflection always happens at runtime regardless of conditional compilation symbols. So [Conditional] is not the right tool for conditional attribute application.

The correct approach is to use #if SYMBOL / #endif blocks around the attribute application itself. This physically removes the attribute from the source code during compilation when the symbol is not defined. For example, you might want a [LogEveryRequest] attribute that should only exist in debug builds. By wrapping it in #if DEBUG, the attribute is not compiled into the release assembly — reflection will never find it because the metadata token is absent.

This technique is often paired with a using static directive or alias to keep code clean. The key trade-off: conditional compilation removes the attribute entirely for non-debug builds, which means your reflective code must handle the case where the attribute is absent (returning null). This is usually fine — the default behaviour (no attribute) is the release path.

using System;
using System.Diagnostics;
using System.Reflection;

public class DebugOnlyAttribute : Attribute
{
    public string Reason { get; }
    public DebugOnlyAttribute(string reason) => Reason = reason;
}

public class RequestHandler
{
    // This attribute only exists in DEBUG builds.
    // In RELEASE, the compiler sees nothing above this method.
#if DEBUG
    [DebugOnly("Tracing all requests for debugging")]
#endif
    public void HandleRequest()
    {
        Console.WriteLine("Request handled.");
    }
}

class Program
{
    static void Main()
    {
        var method = typeof(RequestHandler).GetMethod(nameof(RequestHandler.HandleRequest))!;
        var attr = method.GetCustomAttribute<DebugOnlyAttribute>();

        if (attr != null)
        {
            Console.WriteLine($"Debug attribute found: {attr.Reason}");
        }
        else
        {
            Console.WriteLine("No DebugOnly attribute — we're in RELEASE mode.");
        }
    }
}

Caching Implementation — Production-Ready Attribute Cache

The single most impactful optimisation for attribute-heavy code is caching with ConcurrentDictionary. Below is a production-ready implementation that handles thread safety, lazy initialisation, and cleanup for scenarios where types can be unloaded (e.g., dynamic assemblies in plugin systems).

The pattern is straightforward: define a static generic cache class that stores Lazy<TAttribute> values keyed by MethodInfo (or Type, PropertyInfo, etc.). The Lazy<T> ensures that even under concurrent first access, the attribute is instantiated exactly once per key. The dictionary is static and shared across the application domain, so all requests benefit from the same cache.

For high-traffic endpoints (10k+ RPS), this pattern reduces attribute lookup cost from ~1µs to ~50ns — a 20x improvement. That's the difference between 10ms and 0.5ms CPU time per second at 10k RPS.

using System;
using System.Collections.Concurrent;
using System.Reflection;

/// <summary>
/// Thread-safe cache for attribute lookups.
/// Uses Lazy<T> to ensure attribute is instantiated at most once per key,
/// even under concurrent requests.
/// </summary>
public static class AttributeCache<TAttribute> where TAttribute : Attribute
{
    private static readonly ConcurrentDictionary<MemberInfo, Lazy<TAttribute?>> _cache = new();

    public static TAttribute? Get(MemberInfo member)
    {
        // GetOrAdd is thread-safe: the factory is executed at most once per key.
        return _cache.GetOrAdd(member, mi =>
            new Lazy<TAttribute?>(() => mi.GetCustomAttribute<TAttribute>())
        ).Value;
    }

    /// <summary>
    /// For assemblies that can be unloaded (AssemblyLoadContext),
    /// call this method when the assembly is unloaded to release cached references.
    /// </summary>
    public static void Clear()
    {
        _cache.Clear();
    }
}

// Usage in a middleware or service:
public class RateLimitMiddleware
{
    private static readonly ConcurrentDictionary<MethodInfo, RateLimitAttribute?> _rateLimitCache = new();

    public void ProcessRequest(string endpoint)
    {
        MethodInfo method = GetControllerMethod(endpoint); // hypothetical

        // Using the generic cache:
        var attr = AttributeCache<RateLimitAttribute>.Get(method);
        if (attr != null)
        {
            // Apply rate limiting logic using attr.MaxRequests etc.
        }

        // Alternative direct ConcurrentDictionary (faster for single attribute type):
        var attr2 = _rateLimitCache.GetOrAdd(method, m => m.GetCustomAttribute<RateLimitAttribute>());
    }

    private MethodInfo GetControllerMethod(string endpoint) => typeof(object).GetMethod("ToString")!; // placeholder
}

Attributes in the Real World — ASP.NET Core, JSON, and Data Annotations

You've been using attribute-driven frameworks all along — let's pull back the curtain on three you already know.

In ASP.NET Core, [HttpGet], [HttpPost], and [Route] are custom attributes read by the routing middleware at startup. When the app boots, MVC scans all controller types using reflection, finds methods decorated with HTTP verb attributes, and builds an internal route table. Your method doesn't do anything special — the framework does all the work by reading the metadata.

In System.Text.Json, [JsonPropertyName("order_id")] tells the serializer to map the C# property OrderId to the JSON key order_id. The serializer reads this attribute at serialization time and adjusts its output. [JsonIgnore] tells it to skip the property entirely — useful for passwords or computed values you never want to leak into an API response.

Data Annotations like [Required], [StringLength(100)], and [Range(1, 999)] are read by both ASP.NET Core's model binding (to auto-validate incoming request bodies) and Entity Framework Core (to infer database column constraints). One attribute, two completely separate systems reading it for their own purposes. That's the elegance of metadata: you declare intent once, and any system that cares about it can act on it.

Understanding this pattern means you can build your own mini-frameworks — test runners, CLI argument parsers, config binders — using the same approach the big players use.

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;

// A model that uses Data Annotations for validation
// and System.Text.Json attributes for serialization shape.
public class CreateOrderRequest
{
    // [Required] — model binding will reject this if missing.
    // [StringLength] — EF Core will set VARCHAR(50) in the database.
    [Required(ErrorMessage = "Customer ID is mandatory.")]
    [StringLength(50, ErrorMessage = "Customer ID cannot exceed 50 characters.")]
    [JsonPropertyName("customer_id")] // JSON key uses snake_case
    public string CustomerId { get; set; } = string.Empty;

    [Range(1, 10000, ErrorMessage = "Order amount must be between £1 and £10,000.")]
    [JsonPropertyName("amount_gbp")]
    public decimal AmountGbp { get; set; }

    // [JsonIgnore] — this field is set server-side and must NEVER
    // appear in the outbound JSON response.
    [JsonIgnore]
    public string InternalTrackingCode { get; set; } = Guid.NewGuid().ToString();
}

// A simple validator that manually reads Data Annotation attributes.
// ASP.NET Core does this for you automatically — this shows you what's under the hood.
public static class ManualValidator
{
    public static List<string> Validate(object model)
    {
        var errors = new List<string>();
        Type modelType = model.GetType();

        foreach (PropertyInfo property in modelType.GetProperties())
        {
            // Get the actual value of this property on our model instance.
            object? value = property.GetValue(model);

            // Read ALL validation attributes from this property.
            IEnumerable<ValidationAttribute> validationAttrs =
                property.GetCustomAttributes<ValidationAttribute>();

            foreach (ValidationAttribute validator in validationAttrs)
            {
                // IsValid() is defined on ValidationAttribute base class.
                // Each subclass ([Required], [Range], etc.) overrides it.
                if (!validator.IsValid(value))
                {
                    // FormatErrorMessage fills in placeholders like {0} with the property name.
                    errors.Add($"{property.Name}: {validator.FormatErrorMessage(property.Name)}");
                }
            }
        }

        return errors;
    }
}

class Program
{
    static void Main()
    {
        // === Scenario 1: Invalid request — missing CustomerId, amount out of range ===
        var badRequest = new CreateOrderRequest
        {
            CustomerId = "",         // Fails [Required]
            AmountGbp = 99999m,      // Fails [Range]
            InternalTrackingCode = "TRK-001"
        };

        List<string> validationErrors = ManualValidator.Validate(badRequest);
        Console.WriteLine("=== Validation Errors ===");
        foreach (string error in validationErrors)
            Console.WriteLine($"  ✗ {error}");

        // === Scenario 2: Valid request — serialize to JSON ===
        var goodRequest = new CreateOrderRequest
        {
            CustomerId = "CUST-4421",
            AmountGbp = 149.99m,
            InternalTrackingCode = "TRK-SECRET-002" // This will NOT appear in JSON output
        };

        string json = JsonSerializer.Serialize(
            goodRequest,
            new JsonSerializerOptions { WriteIndented = true }
        );

        Console.WriteLine("\n=== Serialized JSON (note: no InternalTrackingCode) ===");
        Console.WriteLine(json);
    }
}

Attribute Classes — The Compiler's Contract You Must Not Break

Every attribute is just a class that inherits from System.Attribute. That's it. The compiler enforces a rigid contract on these classes: they must have a public constructor, and any public read-write properties become named parameters. Positional parameters are constructor arguments.

Why this matters: The compiler serialises your attribute arguments into the assembly metadata at compile time. If you pass a type that isn't in the allowed parameter type list (bool, byte, char, short, int, long, float, double, string, Type, enum, object, or arrays of those), it silently fails or throws a runtime exception when reflection tries to instantiate the attribute. I've seen production pipelines crash because a junior passed a DateTime as a named parameter thinking it would work — it compiles, then throws at runtime.

Another trap: AttributeUsage controls where your attribute can be applied. If you don't specify it, the compiler assumes all targets. That sounds fine until you accidentally slap a routing attribute on a field. Always explicit. Always include AllowMultiple and Inherited — the defaults (false, true) have bitten teams in microservice configs where base class attributes suddenly vanish or duplicate.

// io.thecodeforge — csharp tutorial

using System;

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
public sealed class RateLimitAttribute : Attribute
{
    // Positional parameter (constructor)
    public int MaxRequestsPerMinute { get; }
    
    // Named parameter (public property with setter)
    public string? ErrorMessage { get; set; }
    
    public RateLimitAttribute(int maxRequestsPerMinute)
    {
        MaxRequestsPerMinute = maxRequestsPerMinute;
        ErrorMessage = $"Rate limit of {maxRequestsPerMinute} per minute exceeded";
    }
}

// This compiles — all allowed types
[RateLimit(100, ErrorMessage = "Slow down!")]
public class PaymentGateway
{
    [RateLimit(50)]  // Valid: Method target
    public void ProcessPayment() { }
}

// This compiles but throws at runtime
// [RateLimit(DayOfWeek.Monday)]  // enum allowed? Yes
// [RateLimit(new object[] { 1, 2 })]  // object array allowed

Compilation of Attributes — How the Metadata Pipeline Really Works

When the compiler sees an attribute, it doesn't magically inject code. It serialises the attribute specification into the assembly's metadata stream as a blob of bytes. The constructor arguments and named parameters are baked in — not evaluated at runtime. This is critical for understanding why you can't pass dynamic values or runtime expressions in attribute arguments.

The compiler takes your attribute class, resolves the constructor overload, evaluates all constant expressions, and encodes everything into a custom attribute blob. At runtime, when you call GetCustomAttribute, the CLR deserialises that blob by calling the constructor with the stored positional args, then setting the named properties. If the deserialisation fails (bad type, missing constructor parameter), you get a CustomAttributeFormatException.

This also means that if you change an attribute class's constructor signature after shipping, all assemblies compiled against the old signature will fail at runtime. I've debugged a NuGet version mismatch where an internal attribute added a required parameter — every plugin in the pipeline blew up with an opaque TypeLoadException. Always treat attribute classes as immutable public API once published.

For the caching junkies: The CLR already caches attribute instances per type/method/property in its own internal metadata tables. Your custom 'production-ready cache' only helps if you're scanning thousands of assemblies on cold start. Otherwise, you're just adding complexity.

// io.thecodeforge — csharp tutorial

using System;
using System.Reflection;

[AttributeUsage(AttributeTargets.Class)]
public sealed class ApiVersionAttribute : Attribute
{
    public int Major { get; }
    public string? DeprecatedMessage { get; set; }
    
    public ApiVersionAttribute(int major) => Major = major;
}

[ApiVersion(2, DeprecatedMessage = "Use v3 endpoint")]
public class LegacyController { }

public class MetadataInspector
{
    public static void Inspect()
    {
        var attr = typeof(LegacyController)
            .GetCustomAttribute<ApiVersionAttribute>();
        
        Console.WriteLine($"Version: {attr.Major}");
        Console.WriteLine($"Deprecation: {attr.DeprecatedMessage ?? "none"}");
        
        // What the JIT actually saw in metadata:
        // Constructor args: [2]
        // Named args: [DeprecatedMessage = "Use v3 endpoint"]
        // All serialized as const blobs at compile time
    }
}

// Output:
// Version: 2
// Deprecation: Use v3 endpoint

Coding the [PropDisplayName] Attribute — Full Implementation Lifecycle

Most tutorials stop at declaring an attribute class. In production, you need three parts: the attribute itself, a reflection reader, and a caching layer. Start with a sealed class inheriting from Attribute. The constructor captures the display name; the property exposes it. Mark it with [AttributeUsage(AttributeTargets.Property, AllowMultiple = false)] to prevent duplicate decorations on the same property. For reading, build a generic extension method that uses Expression Trees to extract the PropertyInfo from a lambda, then checks for the attribute via GetCustomAttribute. Cache the result in a ConcurrentDictionary<PropertyInfo, string> to avoid repeated reflection. This pattern is used in MVVM frameworks and DTO mapping libraries. It frees your UI layer from hard-coded labels and makes localization trivial—just inject a resource manager into the attribute constructor. The key decision: cache on PropertyInfo, not on type, to handle inheritance correctly.

// io.thecodeforge — csharp tutorial

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
public sealed class PropDisplayNameAttribute : Attribute
{
    public string Name { get; }
    public PropDisplayNameAttribute(string name) => Name = name;
}

public static class DisplayExtensions
{
    private static readonly ConcurrentDictionary<PropertyInfo, string> _cache = new();

    public static string DisplayName<T, TProp>(this T obj, Expression<Func<T, TProp>> expr)
    {
        var prop = (PropertyInfo)((MemberExpression)expr.Body).Member;
        return _cache.GetOrAdd(prop, p =>
            p.GetCustomAttribute<PropDisplayNameAttribute>()?.Name ?? p.Name);
    }
}

Keyword Differences for IL — How C# Attributes Translate to Metadata Tokens

C# attributes are syntactic sugar over raw CLI metadata. When you write [Obsolete], the C# compiler emits a .custom instance record in the assembly's metadata tables, not executable IL. The attribute class itself becomes a token in the TypeDef table; its constructor arguments are serialized into a blob in the #Blob heap. The distinction between 'attribute' and 'modifier' in IL is critical: custom attributes are attached to metadata tokens (methods, fields, parameters) via the CustomAttribute table. 'Required modifiers' (modreq) and 'optional modifiers' (modopt) are different—they alter method signatures at the CLR level but are invisible to reflection unless you use GetOptionalCustomModifiers. The C# compiler uses modopt for the is* pattern (e.g., is null) and modreq for caller-info attributes like CallerMemberName. Understanding this separation prevents bugs: a modreq cannot be read by GetCustomAttribute, and a custom attribute cannot enforce calling convention. The CLI spec (ECMA-335) Partitions II and III define these tables.

// io.thecodeforge — csharp tutorial

using System.Runtime.CompilerServices;
using System.Reflection;

public class ModifierCheck
{
    public void Show([CallerMemberName] string caller = "")
    {
        var param = MethodBase.GetCurrentMethod().GetParameters()[0];
        // modreq is NOT a custom attribute
        var mods = param.GetRequiredCustomModifiers();
        Console.WriteLine(mods.Contains(typeof(IsConst))); // False for CallerMemberName
    }
}

23.1 General — Why Attribute Semantics Matter

Attributes in C# are more than metadata decorations; they are compiler-enforced contracts that control runtime behavior through reflection. Section 23.1 of the language spec establishes that attributes are classes inheriting from System.Attribute, but their real power lies in how the compiler binds them to targets like assemblies, types, methods, or parameters. The CLSCompliantAttribute exemplifies this: when applied to an assembly, it forces all public members to adhere to Common Language Specification rules or the compiler emits warnings. Skipping this foundational understanding leads to subtle bugs where attributes silently fail to apply because of target mismatches or inheritance misunderstandings. Always verify your attribute's AttributeUsage to match the intended target; otherwise, the compiler will silently ignore it.

// io.thecodeforge — csharp tutorial
[assembly: CLSCompliant(true)]

public class Calculator
{
    public ulong Compute() => 42; // CS3003: unsigned types not CLS-compliant
}

23.5.5 & 23.5.8 — AsyncMethodBuilder and UnscopedRef Attributes

The AsyncMethodBuilder attribute (23.5.5) lets custom async builders replace the default Task-based infrastructure—critical for high-performance scenarios like pooling or zero-allocation async. For example, ValueTask uses a custom builder internally. Meanwhile, the UnscopedRef attribute (23.5.8) is a safety valve for ref struct safety rules: it marks a ref parameter as intentionally escaping its scope, enabling advanced patterns like returning refs from methods without compiler errors. Both attributes are advanced tools: AsyncMethodBuilder reduces allocations in hot paths, while UnscopedRef relaxes constraints when the developer guarantees lifetime correctness. Misuse of UnscopedRef can create dangling references; only use it when the caller's scope strictly outlives the ref.

// io.thecodeforge — csharp tutorial
[AsyncMethodBuilder(typeof(PoolingAsyncBuilder))]
public ValueTask<int> GetAsync();

public ref int GetRef([UnscopedRef] ref int local)
{
    return ref local; // allowed with UnscopedRef
}

23.5.6 & 23.5.9-10 — Caller Info, EnumeratorCancellation, and ModuleInitializer

Caller-info attributes (23.5.6)—CallerFilePath, CallerLineNumber, CallerMemberName—inject compile-time context into parameters for logging or debugging without runtime overhead. The EnumeratorCancellation attribute (23.5.9) enables cooperative cancellation in async streams by binding a CancellationToken to the enumerator's await foreach loop. ModuleInitializer (23.5.10) runs static code once per assembly load—ideal for eager validation or one-time setup like registering serializer options. These attributes solve specific problems: Caller info replaces boilerplate, EnumeratorCancellation simplifies cancellation in async iteration, and ModuleInitializer replaces old reflection-based initialization hacks. Use them judiciously; ModuleInitializer, for instance, cannot be debugged easily if it throws.

// io.thecodeforge — csharp tutorial
public static void Log(string msg, [CallerMemberName] string member = "")
    => Console.WriteLine($"{member}: {msg}");

[ModuleInitializer]
internal static void Init() => Console.WriteLine("Assembly loaded");