attribute

Allows you to create a custom attribute.

[ attribute(
      AllowOn,
   AllowMultiple=boolean,
   Inherited=boolean
) ]

Parameters

• AllowOn
  Specifies the language elements to which the custom attribute can be applied. Default is System::AttributeTargets::All (see System::AttributeTargets).

• AllowMultiple
  Specifies whether the custom attribute can be applied repeatedly to a construct. Default is FALSE.

• Inherited
  Indicates if the attribute is to be inherited by subclasses. The compiler provides no special support for this functionality; it is the job of the attribute consumers (Reflection, for example) to respect this information. If Inherited is TRUE, the attribute is inherited. If AllowMultiple is TRUE, the attribute will accumulate on the derived member; if AllowMultiple is FALSE, the attribute will override (or replace) in inheritance. If Inherited is FALSE, the attribute will not be inherited. Default is TRUE.

Remarks

You define a custom attribute by placing the attribute attribute on a managed class or struct definition. The name of the class is the custom attribute. For example:

[ attribute(Parameter) ]
public ref class MyAttr {};

defines an attribute called MyAttr that can be applied to function parameters. The class must be public if the attribute is going to be used in other assemblies.

The class's public constructors define the attribute's unnamed parameters. Overloaded constructors allow multiple ways of specifying the attribute, so a custom attribute that is defined the following way:

// cpp_attr_ref_attribute.cpp
// compile with: /c /clr
using namespace System;
[ attribute(AttributeTargets::Class) ]   // apply attribute to classes
public ref class MyAttr {
public:
   MyAttr() {}   // Constructor with no parameters
   MyAttr(int arg1) {}   // Constructor with one parameter
};

[MyAttr]
ref class ClassA {};   // Attribute with no parameters

[MyAttr(123)]
ref class ClassB {};   // Attribute with one parameter

The class's public data members and properties are the attribute's optional named parameters:

// cpp_attr_ref_attribute_2.cpp
// compile with: /c /clr
using namespace System;
[ attribute(AttributeTargets::Class) ]
ref class MyAttr {
public:
   // Property Priority becomes attribute's named parameter Priority
    property int Priority {
       void set(int value) {}
       int get() { return 0;}
   }
   // Data member Version becomes attribute's named parameter Version
   int Version;
   MyAttr() {}   // constructor with no parameters
   MyAttr(int arg1) {}   // constructor with one parameter
};

[MyAttr(123, Version=2)] 
ref class ClassC {};

For a list of possible attribute parameter types, see Custom Attributes.

See User-Defined Attributes for a discussion on attribute targets.

The attribute attribute has an AllowMultiple parameter that specifies whether the custom attribute is single use or multiuse (can appear more than once on the same entity).

// cpp_attr_ref_attribute_3.cpp
// compile with: /c /clr
using namespace System;
[ attribute(AttributeTargets::Class, AllowMultiple = true) ]
ref struct MyAttr {
   MyAttr(){}
};   // MyAttr is a multiuse attribute

[MyAttr, MyAttr()]
ref class ClassA {};

Custom attribute classes are derived directly or indirectly from AttributeCollection, which makes identifying attribute definitions in metadata fast and easy. The attribute attribute implies inheritance from System::Attribute, so explicit derivation is not necessary:

[ attribute(Class) ]
ref class MyAttr

is equivalent to

[ attribute(Class) ]
ref class MyAttr : System::Attribute   // OK, but redundant.

attribute is an alias for System.AttributeUsageAttribute (not AttributeAttribute; this is an exception to the attribute naming rule).

Requirements

Attribute Context

For more information about the attribute contexts, see Attribute Contexts.

Example

// cpp_attr_ref_attribute_4.cpp
// compile with: /c /clr
using namespace System;
[attribute(AttributeTargets::Class)]
ref struct ABC {
   ABC(Type ^) {}
};

[ABC(String::typeid)]   // typeid operator yields System::Type ^
ref class MyClass {};

The Inherited named argument specifies whether a custom attribute applied on a base class will show up on reflection of a derived class.

// cpp_attr_ref_attribute_5.cpp
// compile with: /clr
using namespace System;
using namespace System::Reflection;

[attribute( AttributeTargets::Method, Inherited=false )]
ref class BaseOnlyAttribute { };

[attribute( AttributeTargets::Method, Inherited=true )]
ref class DerivedTooAttribute { };

ref struct IBase {
public:
   [BaseOnly, DerivedToo]
   virtual void meth() {}
};

// Reflection on Derived::meth will show DerivedTooAttribute 
// but not BaseOnlyAttribute.
ref class Derived : public IBase {
public:
   virtual void meth() override {}
};

int main() {
   IBase ^ pIB = gcnew Derived;

   MemberInfo ^ pMI = pIB->GetType( )->GetMethod( "meth" );
   array<Object ^> ^ pObjs = pMI->GetCustomAttributes( true );
   Console::WriteLine( pObjs->Length ) ;
}

2

See Also

Concepts

Attributes Alphabetical Reference

ATL Samples