20 Custom Attributes

Custom attributes add user-defined annotations to the metadata. Custom attributes allow an instance of a type to be stored with any element of the metadata. This mechanism can be used to store application-specific information at compile time and access it either at runtime or when another tool reads the metadata. While any user-defined type can be used as an attribute, CLS compliance requires that attributes will be instances of types whose parent is System.Attribute. The CLI predefines some attribute types and uses them to control runtime behavior. Some languages predefine attribute types to represent language features not directly represented in the CTS. Users or other tools are welcome to define and use additional attribute types.

Custom attributes are declared using the directive .custom. Followed by this directive is the method declaration for a type constructor, optionally followed by a <bytes> in parentheses:

<customDecl> ::=
	<ctor> [ = ( <bytes> ) ]

The <ctor> item represents a method declaration (see Partition II, section 14.4), specific for the case where the method's name is .ctor.

For example:

 .custom instance void myAttribute::.ctor(bool, bool) = ( 01 00 00 01 00 00 ) 

Custom attributes can be attached to any item in metadata, except a custom attribute itself. Commonly, custom attributes are attached to assemblies, modules, classes, interfaces, value types, methods, fields, properties, and events (the custom attribute is attached to the immediately preceding declaration).

The <bytes> item is not required if the constructor takes no arguments. In these cases, all that matters is the presence of the custom attribute.

If the constructor takes parameters, their values shall be specified in the <bytes> item. The format for this "blob" is defined in Partition II, section 22.3.

 Example (informative): The following example shows a class that is marked with the System. SerializableAttribute  and a method that is marked with the System.Runtime. Remoting.OneWayAttribute. The keyword  serializable corresponds to the System.SerializableAttribute. .class public MyClass {      .custom void [mscorlib]System.SerializableAttribute::.ctor ()      .method public static void main() {           .custom void [mscorlib]System.Runtime.Remoting.               OneWayAttribute::.ctor ()            ret      } } 

20.1 CLS Conventions: Custom Attribute Usage

CLS imposes certain conventions upon the use of Custom Attributes in order to improve cross-language operation. See Partition I, section 9.7 for details.

20.2 Attributes Used by the CLI

There are two kinds of Custom Attributes, called (genuine) Custom Attributes and Pseudo Custom Attributes. Custom Attributes and Pseudo Custom Attributes are treated differently, at the time they are defined, as follows:

• A Custom Attribute is stored directly into the metadata; the "blob" which holds its defining data is stored as is. That "blob" can be retrieved later.

• A Pseudo Custom Attribute is recognized because its name is one of a short list. Rather than store its "blob" directly in metadata, that "blob" is parsed, and the information it contains is used to set bits and/or fields within metadata tables. The "blob" is then discarded; it cannot be retrieved later.

Pseudo Custom Attributes therefore serve to capture user directives, using the same familiar syntax the compiler provides for regular Custom Attributes, but these user directives are then stored into the more space-efficient form of metadata tables. Tables are also faster to check at runtime than (genuine) Custom Attributes.

Many Custom Attributes are invented by higher layers of software. They are stored and returned by the CLI, without its knowing or caring what they "mean." But all Pseudo Custom Attributes, plus a collection of regular Custom Attributes, are of special interest to compilers and to the CLI. An example of such Custom Attributes is System.Reflection.DefaultMemberAttribute. This is stored in metadata as a regular Custom Attribute "blob," but reflection uses this Custom Attribute when called to invoke the default member (property) for a type.

The following subsections list all of the Pseudo Custom Attributes and distinguished Custom Attributes, where "distinguished" means that the CLI and/or compilers pay direct attention to them, and their behavior is affected in some way.

In order to prevent name collisions into the future, all custom attributes in the System namespace are reserved for standardization.

20.2.1 Pseudo Custom Attributes

The following table lists the CLI Pseudo Custom Attributes. They are defined in either the System or the System.Reflection namespaces.

Attribute	Description
AssemblyAlgorithmIDAttribute	Records the ID of the hash algorithm used (reserved only).
AssemblyFlagsAttribute	Records the flags for this assembly (reserved only).
DllImportAttribute	Provides information about code implemented within an unmanaged library.
FieldOffsetAttribute	Specifies the byte offset of fields within their enclosing class or value type.
InAttribute	Indicates that a method parameter is an [in] argument.
MarshalAsAttribute	Specifies how a data item should be marshalled between managed and unmanaged code see Partition II, section 22.4.
MethodImplAttribute	Specifies details of how a method is implemented.
OutAttribute	Indicates that a method parameter is an [out] argument.
StructLayoutAttribute	Allows the caller to control how the fields of a class or value type are laid out in managed memory.

Not all of these Pseudo Custom Attributes are specified in this standard, but all of them are reserved and shall not be used for other purposes. For details on these attributes, see the documentation for the corresponding class in the .NET Framework Standard Library Annotated Reference.

The Pseudo Custom Attributes above affect bits and fields in metadata, as follows:

AssemblyAlgorithmIDAttribute: Sets the Assembly.HashAlgId field.

AssemblyFlagsAttribute: Sets the Assembly.Flags field.

DllImportAttribute: Sets the Method.Flags.PinvokeImpl bit for the attributed method; also, adds a new row into the ImplMap table (setting MappingFlags, MemberForwarded, ImportName, and ImportScope columns).

FieldOffsetAttribute: Sets the FieldLayout.OffSet value for the attributed field.

InAttribute: Sets the Param.Flags.In bit for the attributed parameter.

MarshalAsAttribute: Sets the Field.Flags.HasFieldMarshal bit for the attributed field (or the Param.Flags.HasFieldMarshal bit for the attributed parameter); also enters a new row into the FieldMarshal table for both Parent and NativeType columns.

MethodImplAttribute: Sets the Method.ImplFlags field of the attributed method.

OutAttribute: Sets the Param.Flags.Out bit for the attributed parameter.

StructLayoutAttribute: Sets the TypeDef.Flags.LayoutMask sub-field for the attributed type and, optionally, the TypeDef.Flags.StringFormatMask sub-field, the ClassLayout.PackingSiz, and ClassLayout.ClassSize fields for that type.

ANNOTATION

Implementation-Specific (Microsoft): Use of the following Pseudo Custom Attributes renders the assembly that contains them non-portable; a conforming implementation of the CLI may reject such an assembly when it is loaded, or throw an exception at runtime if any attempt is made to access the metadata items set by those Custom Attributes.

Attribute	Description
ComImportAttribute	Provides information about native code reached as a COM component.
OptionalAttribute	Marks a method parameter as optional.
NonSerializedAttribute	Indicates that a field should not be serialized.
PreserveSigAttribute	Specifies HRESULT or retval signature transformation.
SerializableAttribute	Indicates that a type can be serialized.

ANNOTATION

Implementation-Specific (Microsoft):

The Pseudo Custom Attributes above affect bits and fields in metadata, as follows:

• ComImportAttribute: Sets the TypeDef.Flags.Import bit for the attributed type.

• OptionalAttribute: Sets the Param.Flags.Optional bit for the attributed parameter.

• NonSerializedAttribute: Sets the Field.Flags.NotSerialized bit for the attributed field.

• PreserveSigAttribute: Sets the Method.ImplFlags.PreserveSig bit of the attributed method.

• SerializableAttribute: Sets the TypeDef.Flags.Serializable bit for the attributed type.

20.2.2 Custom Attributes Defined by the CLS

The CLS specifies certain Custom Attributes and requires that conformant languages support them. These attributes are located under System.

Attribute	Description
AttributeUsageAttribute	Used to specify how an attribute is intended to be used.
ObsoleteAttribute	Indicates that an element is not to be used.
CLSCompliantAttribute	Indicates whether or not an element is declared to be CLS-compliant through an instance field on the attribute object.

20.2.3 Custom Attributes for CIL-to-Native-Code Compiler and Debugger

ANNOTATION

Implementation-Specific (Microsoft): The following Custom Attributes that control the runtime behavior of a CIL-to-native-code compiler and a runtime debugger are defined in the System.Diagnostics namespace. Their use renders the assembly that contains them non-portable; a conforming implementation of the CLI may reject such an assembly when it is loaded, or throw an exception at runtime if any attempt is made to access those Custom Attributes.

Attribute	Description
DebuggableAttribute	Controls a CIL-to-native-code compiler to produce code that is easier to debug.
DebuggerHiddenAttribute	Specifies that a debugger should step over the attributed method or property.
DebuggerStepThroughAttribute	Specifies that a debugger should step through the attributed method or property (it may step into a method called by this one).

20.2.4 Custom Attributes for Remoting

ANNOTATION

Implementation-Specific (Microsoft): The following Custom Attributes are used to control the behavior of remoting. They are defined in the System.Runtime. Remoting namespace of the Microsoft Base Class Library and are not standardized. Their use renders the assembly that contains them non-portable; a conforming implementation of the CLI may reject such an assembly when it is loaded, or throw an exception at runtime if any attempt is made to access those custom attributes.

Attribute	Description
ContextAttribute	Root for all context attributes.
OneWayAttribute	Marks a method as "fire and forget."
SynchronizationAttribute	Specifies the synchronization options for a class.
ThreadAffinityAttribute	Refinement of Synchronized Context.

20.2.5 Custom Attributes for Security

The following Custom Attributes affect the security checks performed upon method invocations at runtime. They are defined in the System.Security namespace.

Attribute	Description
DynamicSecurityMethodAttribute	Indicates to the CLI that the method requires space to be allocated for a security object.
SuppressUnmanagedCodeSecurityAttribute	Indicates [that] the target method, implemented as unmanaged code, should skip per-call checks.

The following Custom Attributes are defined in the System.Security.Permissions namespace. Note that these are all base classes; the actual instances of security attributes found in assemblies will be sub-classes of these.

Attribute	Description
CodeAccessSecurityAttribute	Base attribute class for declarative security using custom attributes
DnsPermissionAttribute	Custom attribute class for declarative security with DnsPermission
EnvironmentPermissionAttribute	Custom attribute class for declarative security with EnvironmentPermission.
FileIOPermissionAttribute	Custom attribute class for declarative security with FileIOPermission
ReflectionPermissionAttribute	Custom attribute class for declarative security with ReflectionPermission
SecurityAttribute	Base attribute class for declarative security from which CodeAccessSecurityAttribute is derived.
SecurityPermissionAttribute	Indicates whether the attributed method can affect security settings
SiteIdentityPermissionAttribute	Custom attribute class for declarative security with SiteIdentityPermission
SocketPermissionAttribute	Custom attribute class for declarative security with SocketPermission
StrongNameIdentityPermissionAttribute	Custom attribute class for declarative security with StrongNameIdentityPermission
WebPermissionAttribute	Custom attribute class for declarative security with WebPermission

Note that any other security-related Custom Attributes (i.e., any Custom Attributes that derive from System.Security.Permissions.SecurityAttribute) included in an assembly may cause a conforming implementaion of the CLI to reject such an assembly when it is loaded, or throw an exception at runtime if any attempt is made to access those security-related Custom Attributes. (This statement in fact holds true for any Custom Attributes that cannot be resolved; security-related Custom Attributes are just one particular case.)

ANNOTATION

Implementation-Specific (Microsoft): The following security-related Custom Attributes are defined in the Microsoft Base Class Library System.Security. Permissions namespace, and are not standardized. Their use renders the assembly that contains them non-portable; a conforming implementation of the CLI may reject such an assembly when it is loaded, or throw an exception at runtime if any attempt is made to access those Custom Attributes.

Attribute	Description
RegistryPermissionAttribute	Indicates whether the attributed method can access the Registry.
UIPermissionAttribute	Custom attribute class for declarative security with UIPermission.
ZoneIdentityPermissionAttribute	Custom attribute class for declarative security with ZoneIdentityPermission.

20.2.6 Custom Attributes for TLS

A Custom Attribute that denotes a TLS (thread-local storage; see Partition II, section 15.3.3) field is defined in the System namespace.

Attribute	Description
ThreadStaticAttribute	Provides for type member fields that are relative for the thread.

20.2.7 Pseudo Custom Attributes for the Assembly Linker

ANNOTATION

Implementation-Specific (Microsoft): The following Pseudo Custom Attributes are used by the al tool to transfer information between modules and assemblies (they are temporarily attached to a TypeRef to a class called AssemblyAttributesGoHere), then merged by al and attached to the assembly. These attributes are defined in the System.Runtime.CompilerServices namespace. Their use renders the assembly that contains them non-portable; a conforming implementation of the CLI may reject such an assembly when it is loaded, or throw an exception at runtime if any attempt is made to access those Pseudo Custom Attributes.

Attribute	Description
AssemblyCultureAttribute	Specifies which culture an assembly supports.
AssemblyVersionAttribute	String-holding version of assembly (in the format major.minor.build.revision).

ANNOTATION

Implementation-Specific (Microsoft): The Pseudo Custom Attributes above affect bits and fields in metadata, as follows:

• AssemblyCulture: Sets the Assembly.Culture field.

• AssemblyVersion: Sets the Assembly.MajorVersion, MinorVersion, BuildNumber, and RevisionNumber fields.

20.2.8 Custom Attributes Provided for Interoperation with Unmanaged Code

ANNOTATION

Implementation-Specific (Microsoft): The following Custom Attributes are used to control the interoperation with COM 1.x and classical COM. These attributes are located under System.Runtime.InteropServices. More information can also be found in the .NET Framework Standard Library Annotated Reference. Their use renders the assembly that contains them non-portable; a conforming implementation of the CLI may reject such an assembly when it is loaded, or throw an exception at runtime if any attempt is made to access those Custom Attributes.

Attribute	Description
ClassInterfaceAttribute	Specifies how the class is exported to COM (as dispinterface, as a dual interface, or not at all).
ComAliasNameAttribute	Applied to a parameter or field to indicate the COM alias for the parameter or field type.
ComConversionLossAttribute	Indicates that information about a class or interface was lost when it was imported from a type library to an assembly.
ComEmulateAttribute	Used on a type to indicate that it is an emulator type for a different type.
ComRegisterFunctionAttribute	Used on a method to indicate that the method should be called when the assembly is registered for use from COM.
ComSourceInterfacesAttribute	Identifies the list of interfaces that are sources of events for the type.
ComUnregisterFunctionAttribute	Used on a method to indicate that the method should be called when the assembly is unregistered for use from COM.
ComVisibleAttribute	Can be applied to an individual type or to an entire assembly to control COM visibility.
DispIdAttribute	Custom attribute to specify the COM DISPID of a method or field.
GuidAttribute	Used to supply the GUID of a type, an interface, or an entire type library.
HasDefaultInterfaceAttribute	Used to specify that a class has a COM default interface.
IDispatchImplAttribute	Indicates which IDispatch implementation the CLI uses when exposing dual interfaces and dispinterfaces to COM.
ImportedFromTypeLibAttribute	Custom attribute to specify that a module is imported from a COM type library.
InterfaceTypeAttribute	Indicates whether a managed interface is dual, IDispatch, or IUnknown when exposed to COM.
NoComRegistrationAttribute	Used to indicate that an otherwise public, COM-creatable type should not be registered for use from COM applications.
NoIDispatchAttribute	This attribute is used to control how the class responds to queries for an IDispatch interface.
ProgIdAttribute	Custom attribute that allows the user to specify the prog ID of a class.
TypeLibFuncAttribute	Contains the FUNCFLAGS that were originally imported for this function from the COM type library.
TypeLibTypeAttribute	Contains the TYPEFLAGS that were originally imported for this type from the COM type library.
TypeLibVarAttribute	Contains the VARFLAGS that were originally imported for this variable from the COM type library.

20.2.9 Custom Attributes, Various

The following Custom Attributes control various aspects of the CLI:

Attribute	Description
ConditionalAttribute	Used to mark methods as callable, based on some compile-time condition. If the condition is false, the method will not be called.
DecimalConstantAttribute	Stores the value of a decimal constant in metadata.
DefaultMemberAttribute	Defines the member of a type that is the default member used by reflection's InvokeMember.
FlagsAttribute	Custom attribute indicating an enumeration should be treated as a bitfield; that is, a set of flags.
IndexerNameAttribute	Indicates the name by which an indexer will be known in programming languages that do not support indexers directly.
ParamArrayAttribute	Indicates that the method will allow a variable number of arguments in its invocation.