System.Reflection.Emit.TypeBuilder class

  • Article

This article provides supplementary remarks to the reference documentation for this API.

TypeBuilder is the root class used to control the creation of dynamic classes in the runtime. It provides a set of routines that are used to define classes, add methods and fields, and create the class inside a module. A new TypeBuilder can be created from a dynamic module by calling the ModuleBuilder.DefineType method, which returns a TypeBuilder object.

Reflection emit provides the following options for defining types:

  • Define a class or interface with the given name.
  • Define a class or interface with the given name and attributes.
  • Define a class with the given name, attributes, and base class.
  • Define a class with the given name, attributes, base class, and the set of interfaces that the class implements.
  • Define a class with the given name, attributes, base class, and packing size.
  • Define a class with the given name, attributes, base class, and the class size as a whole.
  • Define a class with the given name, attributes, base class, packing size, and the class size as a whole.

To create an array type, pointer type, or byref type for an incomplete type that is represented by a TypeBuilder object, use the MakeArrayType method, MakePointerType method, or MakeByRefType method, respectively.

Before a type is used, the TypeBuilder.CreateType method must be called. CreateType completes the creation of the type. Following the call to CreateType, the caller can instantiate the type by using the Activator.CreateInstance method, and invoke members of the type by using the Type.InvokeMember method. It is an error to invoke methods that change the implementation of a type after CreateType has been called. For example, the common language runtime throws an exception if the caller tries to add new members to a type.

A class initializer is created by using the TypeBuilder.DefineTypeInitializer method. DefineTypeInitializer returns a ConstructorBuilder object.

Nested types are defined by calling one of the TypeBuilder.DefineNestedType methods.

Attributes

The TypeBuilder class uses the TypeAttributes enumeration to further specify the characteristics of the type to be created:

  • Interfaces are specified using the TypeAttributes.Interface and TypeAttributes.Abstract attributes.
  • Concrete classes (classes that cannot be extended) are specified using the TypeAttributes.Sealed attribute.
  • Several attributes determine type visibility. See the description of the TypeAttributes enumeration.
  • If TypeAttributes.SequentialLayout is specified, the class loader lays out fields in the order they are read from metadata. The class loader considers the specified packing size but ignores any specified field offsets. The metadata preserves the order in which the field definitions are emitted. Even across a merge, the metadata will not reorder the field definitions. The loader will honor the specified field offsets only if TypeAttributes.ExplicitLayout is specified.

Known issues

  • Reflection emit does not verify whether a non-abstract class that implements an interface has implemented all the methods declared in the interface. However, if the class does not implement all the methods declared in an interface, the runtime does not load the class.
  • Although TypeBuilder is derived from Type, some of the abstract methods defined in the Type class are not fully implemented in the TypeBuilder class. Calls to these TypeBuilder methods throw a NotSupportedException exception. The desired functionality can be obtained by retrieving the created type using the Type.GetType or Assembly.GetType and reflecting on the retrieved type.