Share via


AttributeUsage (C# and Visual Basic)

Determines how a custom attribute class can be used. AttributeUsage is an attribute that can be applied to custom attribute definitions to control how the new attribute can be applied. The default settings look like this when applied explicitly:

    <System.AttributeUsage(System.AttributeTargets.All, 
                       AllowMultiple:=False, 
                       Inherited:=True)> 
    Class NewAttribute
        Inherits System.Attribute
    End Class

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

In this example, the NewAttribute class can be applied to any attribute-able code entity, but can be applied only once to each entity. It is inherited by derived classes when applied to a base class.

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

<System.AttributeUsage(System.AttributeTargets.All)> 
Class NewAttribute
    Inherits System.Attribute
End Class
[System.AttributeUsage(System.AttributeTargets.All)]
class NewAttribute : System.Attribute { }

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

Imports System


...


<AttributeUsage(AttributeTargets.Property Or AttributeTargets.Field)> 
Class NewPropertyOrFieldAttribute
    Inherits Attribute
End Class
using System;


...


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

If the AllowMultiple argument is set to true, then the resulting attribute can be applied more than once to a single entity, like this:

Imports System


...


    <AttributeUsage(AttributeTargets.Class, AllowMultiple:=True)> 
    Class MultiUseAttr
        Inherits Attribute
    End Class

    <MultiUseAttr(), MultiUseAttr()> 
    Class Class1
    End Class

using System;


...


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

[MultiUseAttr]
[MultiUseAttr]
class Class1 { }

[MultiUseAttr, MultiUseAttr]
class Class2 { }

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

If Inherited is set to false, then the attribute is not inherited by classes that are derived from a class that is attributed. For example:

Imports System


...


<AttributeUsage(AttributeTargets.Class, Inherited:=False)> 
Class Attr1
    Inherits Attribute
End Class

<Attr1()> 
Class BClass

End Class  

Class DClass
    Inherits BClass
End Class
using System;


...


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

[Attr1]
class BClass { }

class DClass : BClass { }

In this case Attr1 is not applied to DClass via inheritance.

Remarks

The AttributeUsage attribute is a single-use attribute--it cannot 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# and Visual Basic).

Example

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

Imports System


...


    ' Create some custom attributes:
    <AttributeUsage(System.AttributeTargets.Class, Inherited:=False)> 
    Class A1
        Inherits System.Attribute
    End Class

    <AttributeUsage(System.AttributeTargets.Class)> 
    Class A2
        Inherits System.Attribute
    End Class    

    <AttributeUsage(System.AttributeTargets.Class, AllowMultiple:=True)> 
    Class A3
        Inherits System.Attribute
    End Class


    ' Apply custom attributes to classes:
    <A1(), A2()> 
    Class BaseClass

    End Class

    <A3(), A3()> 
    Class DerivedClass
        Inherits BaseClass
    End Class


    Public Class TestAttributeUsage
        Sub Main()
            Dim b As New BaseClass
            Dim d As New DerivedClass
            ' Display custom attributes for each class.
            Console.WriteLine("Attributes on Base Class:")
            Dim attrs() As Object = b.GetType().GetCustomAttributes(True)

            For Each attr In attrs
                Console.WriteLine(attr)
            Next

            Console.WriteLine("Attributes on Derived Class:")
            attrs = d.GetType().GetCustomAttributes(True)
            For Each attr In attrs
                Console.WriteLine(attr)
            Next            
        End Sub
    End Class

using System;


...


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

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

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

// Apply custom attributes to classes:
[A1, A2]
class BaseClass { }

[A3, A3]
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:
A1
A2
Attributes on Derived Class:
A3
A3
A2

See Also

Reference

Reflection (C# and Visual Basic)

Attributes (C# and Visual Basic)

Creating Custom Attributes (C# and Visual Basic)

Accessing Attributes by Using Reflection (C# and Visual Basic)

Attribute

System.Reflection

Concepts

C# Programming Guide

Other Resources

Visual Basic Programming Guide

Extending Metadata Using Attributes