AttributeUsage (C#)

Determines how a custom attribute class can be used. AttributeUsageAttribute is an attribute you apply to custom attribute definitions. The AttributeUsage attribute enables you to control:

  • Which program elements attribute may be applied to. Unless you restrict is usage, an attribute may be applied to any of the following program elements:
    • assembly
    • module
    • field
    • event
    • method
    • param
    • property
    • return
    • type
  • Whether an attribute can be applied to a single program element multiple times.
  • Whether attributes are inherited by derived classes.

The default settings look like the following example when applied explicitly:

[System.AttributeUsage(System.AttributeTargets.All,
                   AllowMultiple = false,
                   Inherited = true)]
class NewAttribute : System.Attribute { }

In this example, the NewAttribute class can be applied to any supported program element. But it can be applied only once to each entity. The attribute is inherited by derived classes when applied to a base class.

The AllowMultiple and Inherited arguments are optional, so the following code has the same effect:

[System.AttributeUsage(System.AttributeTargets.All)]
class NewAttribute : System.Attribute { }

The first AttributeUsageAttribute argument must be one or more elements of the AttributeTargets enumeration. Multiple target types can be linked together with the OR operator, like the following example shows:

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field)]
class NewPropertyOrFieldAttribute : Attribute { }

Beginning in C# 7.3, attributes can be applied to either the property or the backing field for an auto-implemented property. The attribute applies to the property, unless you specify the field specifier on the attribute. Both are shown in the following example:

class MyClass
{
    // Attribute attached to property:
    [NewPropertyOrField]
    public string Name { get; set; }

    // Attribute attached to backing field:
    [field:NewPropertyOrField]
    public string Description { get; set; }
}

If the AllowMultiple argument is true, then the resulting attribute can be applied more than once to a single entity, as shown in the following example:

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
class MultiUse : Attribute { }

[MultiUse]
[MultiUse]
class Class1 { }

[MultiUse, MultiUse]
class Class2 { }

In this case, MultiUseAttribute can be applied repeatedly because AllowMultiple is set to true. Both formats shown for applying multiple attributes are valid.

If Inherited is false, then the attribute isn't inherited by classes derived from an attributed class. For example:

[AttributeUsage(AttributeTargets.Class, Inherited = false)]
class NonInheritedAttribute : Attribute { }

[NonInherited]
class BClass { }

class DClass : BClass { }

In this case NonInheritedAttribute isn't applied to DClass via inheritance.

Remarks

The AttributeUsage attribute is a single-use attribute--it can't be applied more than once to the same class. AttributeUsage is an alias for AttributeUsageAttribute.

For more information, see Accessing Attributes by Using Reflection (C#).

Example

The following example demonstrates the effect of the Inherited and AllowMultiple arguments to the AttributeUsageAttribute attribute, and how the custom attributes applied to a class can be enumerated.

using System;

// Create some custom attributes:
[AttributeUsage(AttributeTargets.Class, Inherited = false)]
class FirstAttribute : Attribute { }

[AttributeUsage(AttributeTargets.Class)]
class SecondAttribute : Attribute { }

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
class ThirdAttribute : Attribute { }

// Apply custom attributes to classes:
[First, Second]
class BaseClass { }

[Third, Third]
class DerivedClass : BaseClass { }

public class TestAttributeUsage
{
    static void Main()
    {
        BaseClass b = new BaseClass();
        DerivedClass d = new DerivedClass();

        // Display custom attributes for each class.
        Console.WriteLine("Attributes on Base Class:");
        object[] attrs = b.GetType().GetCustomAttributes(true);
        foreach (Attribute attr in attrs)
        {
            Console.WriteLine(attr);
        }

        Console.WriteLine("Attributes on Derived Class:");
        attrs = d.GetType().GetCustomAttributes(true);
        foreach (Attribute attr in attrs)
        {
            Console.WriteLine(attr);
        }
    }
}

Sample Output

Attributes on Base Class:
FirstAttribute
SecondAttribute
Attributes on Derived Class:
ThirdAttribute
ThirdAttribute
SecondAttribute

See Also