Exported Type Conversion

Article
11/03/2006

This topic describes how the export process converts the following types:

Classes
Interfaces
Value types
Enumerations

In general, exported types retain the same name they had within an assembly, excluding the namespace associated with the managed name. For example, the type A.B.IList in the following code sample converts to IList in the exported type library. A COM client can refer to the type as IList instead of A.B.IList.

Namespace A
    Namespace B
        Interface IList
               …       
        End Interface
    End Namespace
End Namespace

namespace A {
    namespace B {
        interface IList {
               …
        }
    }
}

With this approach, type names within an assembly can potentially collide because types in different namespaces can have the same name. When the export process detects a collision, it retains the namespace to eliminate naming ambiguities. The following code sample shows two namespaces with the same type name.

Namespace A
    Namespace B
        Public Class LinkedList
            Implements IList
        End Class
      
        Public Interface IList
        End Interface 
    End Namespace
End Namespace

Namespace C
    Public Interface IList
    End Interface
End Namespace

namespace A {
    namespace B {
        public class LinkedList : IList {…}
        public interface IList {…}
    }
}
   namespace C {
       public interface IList {…}
}

The following type library representation shows the resolution of each type name. Also, since periods are not valid in type library names, the export process replaces each period with underscores.

Type library representation

library Widgets 
{
    […]
    coclass LinkedList 
    {
        interface A_B_IList
    };

    […]
    interface A_B_IList {…};
    […]
    interface C_IList {…};
};

The export process also automatically generates a programmatic identifier (ProgId) by combining the namespace and type name. For example, the ProgId generated for the managed LinkedList class shown in the previous examples is A.B.LinkedList.

Combining the namespace and type name can result in an invalid ProgId. A ProgId is limited to 39 characters and can contain no punctuation characters other than periods. To avoid these limitations, you can specify a ProgId in your source code by applying the ProgIdAttribute, rather than allowing the export process to generate an identifier for you.

Classes

The export process converts each public class (that omits the ComVisible (false) attribute) in an assembly to a coclass in a type library. An exported coclass has neither methods nor properties; however, it retains the name of the managed class and implements all interfaces explicitly implemented by the managed class.

The following code example shows the definition of the IShape interface and the Circle class, which implements IShape. The converted type library representation follows the code example.

Public Interface IShape
    Sub Draw()
    Sub Move(x As Integer, y As Integer)
End Interface

Class Circle
    Implements IShape
    Sub Draw Implements IShape.Draw
    …    
    Sub Move(x As Integer, y As Integer) Implements IShape.Move
    …
    Sub Enlarge(x As Integer)
    …
End Class

public interface IShape {
    void Draw();
    void Move(int x, int y);
}
class Circle : IShape  {
    void Draw();
    void Move(int x, int y);
    void Enlarge(int x);
}

Type library representation

[ uuid(…), dual, odl, oleautomation ]
interface IShape : IDispatch {
    HRESULT Draw();
    HRESULT Move(int x, int y);
}

[ uuid(…) ]
coclass Circle {
    interface IShape;
}

Each coclass can implement one other interface, called the class interface, which the export process can generate automatically. The class interface exposes all methods and properties available in the original managed class, thereby enabling COM clients to access them by calling through the class interface.

You can assign a specific universal unique identifier (UUID) to the class by applying the GuidAttribute immediately above the managed class definition. During the conversion process, the export process transfers the value provided to the GuidAttribute to the UUID in the type library. Otherwise, the export process obtains UUIDs from a hash that includes the complete name of the class, including the namespace. Using the full name ensures that a class with a given name in a given namespace always generates the same UUID, and that two classes with different names never generate the same UUID.

Abstract classes and classes without public, default constructors are marked with the noncreatable type library attribute. Other type library attributes that apply to coclasses, such as licensed, hidden, restricted, and control are not set.

Interfaces

The export process converts managed interfaces to COM interfaces with the same methods and properties as the managed interface, but the method signatures differ considerably.

Interface Identities

COM interfaces include an interface identifier (IID) to distinguish one interface from another. You can assign a fixed IID to any managed interface by applying the GuidAttribute attribute. If you omit this attribute and do not assign a fixed IID, the export process automatically assigns one during the conversion. A runtime-assigned IID comprises the interface name (including namespace) and the complete signature of all methods defined within the interface. By reordering the methods on the managed interface or by changing method argument and return types, you change the IID assigned to that interface. Changing a method name does not affect the IID.

Using the QueryInterface method implemented by the runtime, COM clients can obtain an interface having either a fixed IID or runtime-assigned IID. IIDs generated by the runtime are not persisted within the metadata for the type.

Interface Types

Unless you specify otherwise, the export process converts all managed interfaces to dual interfaces in a type library. Dual interfaces enable COM clients to choose between early and late binding.

You can apply the InterfaceTypeAttribute attribute to an interface to selectively indicate that the interface should be exported as a dual interface, an IUnknown-derived interface, or a dispatch-only interface (dispinterface). All exported interfaces extend directly from either IUnknown or IDispatch, regardless of their inheritance hierarchy in managed code.

The following code example shows the optional values for controlling the interface type. Once exported to a type library, these options produce the results shown in the type library representation that follows the code.

' Creates a Dual interface by default.
Public Interface InterfaceWithNoInterfaceType
    Sub test()
End Interface

' Creates a Dual interface explicitly.
<InterfaceType(ComInterfaceType.InterfaceIsDual)> _
Public Interface InterfaceWithInterfaceIsDual
    Sub test()
End Interface

' Creates an IUnknown interface (not dispatch).
<InterfaceType(ComInterfaceType.InterfaceIsIUnknown)> _
Public Interface InterfaceWithInterfaceIsIUnknown
    Sub test()
End Interface

' Creates a Dispatch-only interface (dispinterface).
<InterfaceType(ComInterfaceType.InterfaceIsIDispatch)> _
Public Interface InterfaceWithInterfaceIsIDispatch
    Sub test()
End Interface

// Creates a Dual interface by default.
public interface InterfaceWithNoInterfaceType {
    void test();
}
// Creates a Dual interface explicitly.
[InterfaceType(ComInterfaceType.InterfaceIsDual)]
public interface InterfaceWithInterfaceIsDual {
    void test();
}
// Creates an IUnknown interface (not dispatch).
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface InterfaceWithInterfaceIsIUnknown {
    void test();
}
// Creates a Dispatch-only interface(dispinterface).
[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
public interface InterfaceWithInterfaceIsIDispatch {
    void test();
}

Type library representation

[ odl, uuid(…), dual, oleautomation ]
interface InterfaceWithNoInterfaceType : IDispatch {
    HRESULT test();
};
[ odl, uuid(…), dual, oleautomation ]
interface InterfaceWithInterfaceIsDual : IDispatch {
     HRESULT test();
};
[ odl, uuid(…), oleautomation ]
interface InterfaceWithInterfaceIsIUnknown : IUnknown {
     HRESULT test();
};
[ uuid(…) ]
dispinterface InterfaceWithInterfaceIsIDispatch {
     properties:
     methods:
         void test();
};

Most interfaces are marked with the odl, and oleautomation type library attributes during the export process. (Dispinterfaces are the exception). Dual interfaces are marked with the dual type library attribute. A dual interface derives from the IDispatch interface, but it also exposes vtable slots for its methods.

Class Interfaces

For a complete description of the class interface and for usage recommendations, see Introducing the Class Interface. The export process can generate this interface automatically on behalf of a managed class without an interface explicitly defined in managed code. COM clients cannot access class methods directly.

The following code example shows a base class and a derived class. Neither class implements an explicit interface. The export process provides a class interface for both managed classes.

Public Class BaseClassWithClassInterface
    Private Shared StaticPrivateField As Integer
    Private PrivateFld As Integer
   
    Private Property PrivateProp() As Integer
        Get
            Return 0
        End Get
        Set
        End Set
    End Property
   
    Private Sub PrivateMeth()
        Return
    End Sub 
    Friend Shared StaticInternalField As Integer
    Friend InternalFld As Integer
   
    Friend Property InternalProp() As Integer
        Get
            Return 0
        End Get
        Set
        End Set
    End Property
   
    Friend Sub InternalMeth()
        Return
    End Sub 
    Public Shared StaticPublicField As Integer
    Public PublicFld As Integer
   
    Public Property PublicProp() As Integer
        Get
            Return 0
        End Get
        Set
        End Set
    End Property
   
    Public Sub PublicMeth()
        Return
    End Sub
End Class
 
Public Class DerivedClassWithClassInterface
    Inherits BaseClassWithClassInterface
   
    Public Sub Test()
        Return
    End Sub
End Class

public class BaseClassWithClassInterface {
    private  static int  StaticPrivateField;
    private  int  PrivateFld;
    private  int  PrivateProp{get{return 0;} set{;}}
    private  void PrivateMeth() {return;}

    internal static int  StaticInternalField;
    internal int  InternalFld;
    internal int  InternalProp{get{return 0;} set{;}}
    internal void InternalMeth() {return;}

    public   static int  StaticPublicField;
    public   int  PublicFld;
    public   int  PublicProp{get{return 0;} set{;}}
    public   void PublicMeth() {return;}
}

public class DerivedClassWithClassInterface : BaseClassWithClassInterface {
    public void Test() {return;}
}

Type library representation

[odl,uuid(…), hidden, dual, nonextensible, oleautomation]
interface _BaseClassWithClassInterface : IDispatch {
     [id(00000000),propget]   HRESULT ToString([out, retval] BSTR* p);
     [id(0x60020001)]         HRESULT Equals([in] VARIANT obj, 
                                [out, retval] VARIANT_BOOL* p);
     [id(0x60020002)]         HRESULT GetHashCode([out,retval] long* p);
     [id(0x60020003)]         HRESULT GetType([out, retval] _Type** p);
     [id(0x60020004),propget] HRESULT PublicProp([out,retval] long* p);
     [id(0x60020004),propput] HRESULT PublicProp([in] long p);
     [id(0x60020006)]         HRESULT PublicMeth();
     [id(0x60020007),propget] HRESULT PublicFld([out, retval]long* p);
     [id(0x60020007),propput] HRESULT PublicFld([in] long p);
};
[odl,uuid(…), hidden, dual, nonextensible, oleautomation]
interface _DerivedClassWithClassInterface : IDispatch {
     [id(00000000),propget]   HRESULT ToString([out, retval] BSTR* p);
     [id(0x60020001)]         HRESULT Equals([in] VARIANT obj, 
                                [out, retval] VARIANT_BOOL* p);
     [id(0x60020002)]         HRESULT GetHashCode([out,retval] long* p);
     [id(0x60020003)]         HRESULT GetType([out, retval] _Type** p);
     [id(0x60020004),propget] HRESULT PublicProp([out,retval] long* p);
     [id(0x60020004),propput] HRESULT PublicProp([in] long p);
     [id(0x60020006)]         HRESULT PublicMeth();
     [id(0x60020007),propget] HRESULT PublicFld([out, retval]long* p);
     [id(0x60020007),propput] HRESULT PublicFld([in] long p);
     [id(0x60020008)]         HRESULT Test();
}

The exported class interfaces have the following characteristics:

Each class interface retains the name of the managed class, but is prefixed with an underscore. When an interface name conflicts with a previously defined interface name, the new name is appended with an underscore and an incremental number. For instance, the next available name for _ClassWithClassInterface is _ClassWithClassInterface_2.
The export process always generates new interface identifiers (IID). You cannot explicitly set the IID of the class interface.
By default, both class interfaces derive from IDispatch interfaces.
The interfaces have ODL, dual, hidden, nonextensible and oleautomation attributes.
Both interfaces have all the public members of its base class (System.Object).
They do not contain the private or internal members of the class.
Each member is automatically assigned a unique DispId. The DispIds can be set explicitly by applying DispIdAttribute to the member of the class.
Method signatures are transformed to return HRESULTs and have [out, retval] parameters.
The properties and fields are transformed into [propget], [propput], and [propputref].

Default Interface

COM has the notion of a default interface. Members of the default interface are treated as the members of the class by late-bound languages like Visual Basic. In the .NET Framework, there is no need for a default interface because classes themselves can have members. However, when exposing classes to COM, classes are much easier to use if they have a default interface.

When a managed class is exported to a type library as a coclass, one interface is typically identified as the default interface for the class. If no interface is identified as the default in the type library, most COM applications assume that the first implemented interface is the default interface of that coclass.

As the following code example shows, the export process converts a managed class that has no class interface and marks the first implemented interface as the default in the exported type library. The type library representation of the converted class follows the code example.

<ClassInterface(ClassInterfaceType.None)> _
Public Class ClassWithNoClassInterface
    Implements IExplicit
    Implements IAnother
    Sub M()
    …
End Class

[ClassInterface(ClassInterfaceType.None)]
public class ClassWithNoClassInterface : IExplicit, IAnother {
    void M();   
}

Type library representation

coclass ClassWithNoClassInterface {
    [default] IExplicit; 
    IAnother;
}

The export process always marks the class interface as the default interface for the class, regardless of any other interface that the class implements explicitly. The following example shows two classes.

<ClassInterface(ClassInterfaceType.AutoDispatch)> _
Public Class ClassWithAutoDispatch
    Implements IAnother
    Sub M()
    …
End Class 
 
<ClassInterface(ClassInterfaceType.AutoDual)> _
Public Class ClassWithAutoDual
    Implements IAnother
    Sub M()
    …
End Class

[ClassInterface(ClassInterfaceType.AutoDispatch)]
public class ClassWithAutoDispatch : IExplicit, IAnother {
    void M();   
}

[ClassInterface(ClassInterfaceType.AutoDual)]
public class ClassWithAutoDual : IExplicit, IAnother {
    void M();   
}

Type library representation

// ClassWithAutoDispatch: IDispatch
coclass ClassWithAutoDispatch {
    [default] _ClassWithAutoDispatch;
    interface _Object;
    IExplicit;
    IAnother;
}
interface _ClassWithAutoDual {…}

coclass ClassWithAutoDual {
    [default] _ClassWithAutoDual; 
    IExplicit;
    IAnother;
}

Value Types

Value types (types that extend System.Value) are exported to type libraries as C-style structures with the type definition. The layout of the structure members is controlled with the StructLayoutAttribute attribute, which is applied to the type. Only the fields of the value type are exported. If a value type has methods, they are inaccessible from COM.

For example:

[StructLayout(LayoutKind.Sequential)]
public struct Point {
    int x;
    int y;
    public void SetXY(int x, int y){ 
        this.x = x;
        this.y = y;
    }
};

The Point value type is exported to COM as a point typedef, as shown in the following example:

typedef 
[uuid(…)]
struct tagPoint {
    short x;
    short y;
} Point;

Notice that the conversion process removes the SetXY method from the typedef.

Enumerations

The export process adds a managed enumeration to type libraries as an enumeration with the member names altered to ensure the unique member naming. To ensure that each member name is unique, Tlbexp.exe prefixes an underscore to the name of the enumeration to each member during the export process. For example, the following simple enumeration produces a set of type library representations.

Enum DaysOfWeek {
    Sunday = 0;
    Monday;
    Tuesday;
    …
};

Type library representation

enum DaysOfWeek {
    DaysOfWeek_Sunday = 0;
    DaysOfWeek_Monday;
    DaysOfWeek_Tuesday;
    …
};

The runtime scopes managed enumeration members to the enumeration in which they belong. For instance, all references to Sunday in the DaysOfWeek enumeration, shown in the previous example, must be qualified with DaysOfWeek. You cannot reference Sunday in place of DaysOfWeek.Sunday. Unique member naming is a requirement of COM enumerations.

Share via

Exported Type Conversion

Type library representation

Classes

Type library representation

Interfaces

Interface Identities

Interface Types

Type library representation

Class Interfaces

Type library representation

Default Interface

Type library representation

Type library representation

Value Types

Enumerations

Type library representation

See Also

Concepts

Other Resources

Additional resources