COM interop in .NET, an object oriented approach

In this article I will give you an overview of COM-interop in the .NET platform. COM has been part of Windows for quite some time now and is supported by almost any Windows development tool. The widest supported is (OLE) automation in which a client uses objects from other applications or from libraries. .NET is targeted as a platform for the future but it does provide a very good support for COM and specially automation.

After an introduction to COM automation objects and the COM event mechanism I will use an automation object in a C# application. This .NET client will call methods and properties on the automation object and will respond to events fired by the automation object. Next comes exposing a .NET class to non .NET clients using COM. The class built will fire events to any client interested.

In the process of creating the automation class we will meet many object oriented features of the C# language and the .NET framework. Starting with base classes we will end up with a fully functional connectable automation object. 

COM - .NET Interoperabilty 

Both .NET and COM care a lot about interoperability. COM is entirely dedicated to it, it is a combination of a protocol and an API which software components can use to communicate with each other. COM is independent of the development tool used to build the component, as long as the tools follows the COM specification and uses the right API functions the communication will work.

.NET is an interoperability standard on itself, implemented by C#, VB.NET or any other of the large number of programming languages for the .NET framework. Code running inside the framework is called managed code, as it is run and managed by the framework's Common Language Runtime. Besides the tight interoperability between native .NET components .NET has a great runtime support for interoperability with unmanaged code. Unmanaged code is all code which is not aware of the CLR. It does include classical Windows DLL's but the main part of the .NET support is dedicated to interoperability with COM.

In the heart of interoperability lies metadata. Metadata is important in separating the implementation and the interface of software. Hidden inside the component is its implementation with all details needed to make it work right. The interface describes the exposed functionality of a class, what methods are available, what parameters do the methods have, what is the type of the parameters and what is the return type of the method. .NET stores its metadata in the assemblies (executable components) themselves. So anybody who has a .NET assembly (which will be a DLL or exe) can inspect it to see what's inside and how that should be used. COM writes it's metadata in a type-library, which can be a separate TLB file, included as a resource in the component itself or just missing. A reference to all type-libraries and described interfaces is found in the Windows registry. A client who wants to use a COM class can do so by supplying just a name or an ID of the class to an API function. It does not  have to know the physical location of the implementing binary, all of that can be found in the registry. .NET development tools can read registry and type-libraries and wrap COM classes up in .NET classes.

In a COM type-library classes and interfaces are described. A COM class has just two methods. One to create a new object of the class and one to create a new remote object. Every COM class implements one ore more of the interfaces described in the type library as well as the base COM interfaces Iunknown and Idispatch. The constructor will return the creating client an interface variable. The client can execute all methods and properties of the interface returned. Properties of a COM class are implemented the same way as properties in a .NET class, they consist of a property setter and/or a property getter method. So all accesses to an automation object are actually methods calls. 

A client cannot destroy a COM-object. In .NET the system garbage collector keeps track of unused objects, freeing all objects no longer referenced by anything. COM uses reference counting to manage the lifespan of an object, this is a count of the number of clients having a reference to the object, when it drops to 0 the object will destroy itself. A client adds a reference to the object when it starts using it and releases it when ready. Ref(erence)counting in COM is a responsibility of all clients using the object, in languages like Visual Basic (for Applications) or Delphi it is handled by the compiler, in C++ it is the responsibility of the programmer to make calls to the interfaces's addref and release methods. Needless to say this is sensitive to bugs.

The .NET tools cannot just read type-libraries, they can create and register them as well. Doing so you can expose your .NET classes to any COM enabled client. Which makes COM a bridge to use "legacy" code in .NET and a bridge to use .NET objects in "legacy" application like MS-Office, Visual Basic, Delphi, VB-Script, JavaScript, Powerbuilder, Oracle, or almost any other (in-)conceivable tool.

Connectable automation objects

COM covers a large amount of API functions and interfaces. By far the most used interface is Idispatch. Classes which implement this interface are named automation objects. With Idispatch the functionality of classes is exposed in three ways :

1. It's methods can be called directly from the method table, or vtable, of the object, the layout of this vtable is described in the type-library. A compiler will map calls to vtable entries. This is called vtable binding, these days it is called early binding as well.
2. Every method of the class has a so-called dispid, it usually corresponds to the sequence number of the method in the vtable. All methods can be called by making a call to Idispatches Invoke method, passing it the dispId of the method. The compiler will read these dispid's from the typelibrary and map calls to the objects method to Invoke calls with the associated dispID. This used to be called early binding, a better term is dispID binding. Automation interfaces used in this manner are usually called dispinterfaces.
3. Every Idispatch interface has beside the Invoke method a GetIdsOfNames method. This takes the name of the method or property in string format, performs a run-time lookup in the type-library for the dispID after which the method can be executed using the Invoke method. A script interpreter will do this to map script calls to methods. This is called late binding.

An enormous amount of tools supports Idispatch, and so a lot of clients can call methods on automation (COM) objects. But what if a server object wants to make callbacks to its clients ? This is implemented in automation through an automation event mechanism. In the COM specification a couple of interfaces are defined and there are some API functions which know how to work with these interfaces.

The server will need something  on which to fire its events. The client has to supply the server a so called outgoing interface, this is a dispinterface to an object which is implemented by the client. The server will make calls to the methods of this interface, for every distinct event there will be a method. And so the server makes calls on an object in the client. Which events the client understands corresponds to the interface-methods the server can call. This interface will be declared in the type-library of the server, so every client will know the layout of the outgoing interface it has to implement. The client-side object which implements this interface is called an eventsink. As you pour water into the kitchen sink, an automation server can pour events into the eventsink of a client. What happens with the water is not your concern, what happens with the events is not the servers concern. The server is the source of events. In this scenario it is no longer very clear who is calling who, so the names client and server are somewhat confusing. That's why a server is called a connectable object or an event source. The client is the event sink.

The client connects its event-sink to the source using an IConnectionPoint interface. The source can sink events to more than one client, all connections are managed through the IConnectionPointContainer interface. The client will get the container interface and the connectionpoint in there to hook up it's event-sink. If a server wants to be an event source and support the sinking (firing) of events in the standard automation way it has to provide an implementation of this IConnectionPointContainer interface.

Runtime Interop

Interoperability in a .NET application is handled by interop. At runtime .NET interop sits between the COM- and the .NET- component. It has to do a couple of things. First it should create the object "on the other side" and provide an interface to it. After which it should guide calls to methods and properties on this interface and transport any data from one side to the other. The largest problem in all this is that .NET is running in the managed CLR environment and COM is not. These are two separated worlds, .NET cannot read or write outside it's guarded managed data and no outsider is allowed in to read or write any data in the managed world.

As a solution for this the .NET Common Language Runtime has two proxies, the Runtime Callable Wrapper (RCW) and the COM Callable Wrapper (CCW). .NET code making calls to a COM object will actually call the RCW, which will communicate with the COM object and so act as a passage to the unmanaged world outside. The RCW will hold the reference to the COM object and it will perform marshalling. Marshalling involves the copying and (when needed) translation of data, for instance the internal string format of a COM and a .NET string are different.

An external client trying to access a COM object implemented in .NET will actually make calls to the CCW. This CCW will construct and manage the actual .NET objects. It also does the marshalling, besides translating strings it takes care of method results. All COM clients expect a method to have a hResult return type, it's value indicating the success of the call. Any method (function) return values should be passed in out parameters. In .NET you can code your methods in .NET style, marshalling will do all translations needed.

In the .NET framework Class Library (FCL) there is the namespace System.Runtime.InteropServices. A great number of COM types are declared in this namespace. You will find interfaces like IConnectionPointContainer, named UCOMIConnectionPointContainer, UCOM stands for unmanaged COM. You will find COM defined structures like CONNECTDATA which holds the data of a client connection. You will find attribute classes like InterfaceType which specifies the Idispatch type in the metadata of the automation class. You will find COM defined enumerations like COMinterfaceType which is used as a parameter for the InterfaceType attribute. A very important member of the namespace is the Marshall object. This object does the actual marshalling and has an enormous amount of members who will sound very familiar to "traditional" COM developers.

Using COM objects in a .NET application

I have a small FileManager utility. On a windows form it shows a directory outline of the files on my computer. If you select a directory in the tree a list of all the files in there is presented. One or a couple of files can be selected. The utility is implemented as an in-process automation server, it is a DLL which has to be used via automation. When a file or directory is selected It does fire events to any clients interested. The original utility was built in Delphi.

In Visual Studio I will create a new Windows Application. It is a form with a listbox, a trackbar and a progressbar. My .NET C# application needs the type-library of the utility. I have to add it to the references of the project. The dialog to do this is found in the solution explorer, my FileManager automation class is found under the COM tab.

The .NET tools will now generate a .NET class which wraps up the automation class. In the applications form I will declare a private variable for an object of this class. Of the automation class I will use the Ifilemanager interface to call it's methods and its connectionpoints to hook in my eventsinks. All are wrapped up together in this generated .NET FileManager class.

The FileManager object is created just like any other C# (.NET) object. Inspecting the class will show a variety of properties and methods. You will see all members of System.Object like Finalize() and ToString(). In the same list are all properties and methods of the COM object, like FileMask and Select. The property FileMask is set after constructing the object, it is set to a plain C# string.  The automation object's properties are fully transparent, to the code there is no difference between the properties declared in .NET's System.Object and those declared in the automation class.

You will also see that the FileManager supports events. The fastest way to see all this is using the VS IDE code completion. 

The FileManager class supports two events : OnDirectoryChanged happens when a new directory is selected. OnSelectionChanged happens when the collection of selected files changes. The complexities of creating an eventsink are handled by .NET's interopservices. The events property is of type IFileZapperEvents_OnDirectoryChangedEventHandler, this type inherits directly from System.MultiCastDelegate, just like all other event handlers in .NET. In .NET  event-handlers work with so called delegate objects. The eventhandler maintains a list of these delegate objects, when the event occurs all objects in the list will be notified. The events in the typelibrary are translated to declarations of delegate classes, objects of these classes can be added to the event-handler of the FileManager object.

The OnDirectoryChanged event had a string parameter declared in which the eventsource will pass the name of the new directory. The associated method of the form catches the incoming name :

When the user selects another file the trackbar and the progressbar will advance. When the users selects another directory the directoryname will show in the listbox. 

Now I have done all coding to use the automation object and sinks it's events in my C# application. As a result the "legacy" automation object built in Delphi works tightly together with the .NET app.

Building classes in .net

Before I will start with exposing a .NET class via COM-interop I do need a couple of base classes to assemble the class and manage collections of clients connected to its objects. I will start with a simple class to hold constants needed and end with a class which supports multiple COM interfaces. In the process a lot of the beautiful possibilities of object orientation in .NET will pass the scene.

.NET is fully object oriented, everything is an object. Including your application itself, it is an object whose Main method is executed to run the app. Object orientation is followed very  strictly in  .NET, you cannot declare any loose procedures or constants. All declarations have to be in the form of class declarations. A .NET class can be static, which means that no objects of this class can be created. At startup the class is constructed after which all code can use the properties of this class. A static class can have a constructor, this is executed the first time the class is accessed. A static class is a good place to house constants used in the metadata.

The following class manages a group of identifying GUID's, these  are initially coded as strings. The (static) constructor will use these strings to construct real GUID's, of type System.Guid, at startup.

Interfaces are declared quite straightforward by enumerating their methods.

Interfaces are implemented by classes. In the declaration of the class is included a list of the interfaces it will implement. After which the class has to provide the methods declared in the interface.

Base classes

Classes offer a lot of very nice possibilities in .NET. I will use a couple of them to build a couple of tagged object classes. These classes combine an object with a tagstring. This name tag will be used to compare or find objects in an arraylist, where two objects with equal tag values will be considered equal. These base classed are housed in a .NET class library so that any other project can use the classes by adding the library to its references list.

It all starts with the TaggedObject class. This class stores its nametag in a private string. The tag is exposed as a readonly NameTag property, the visibility of the property is limited to the assembly. Derived classes in the same assembly can read the nametag, external users of the class don't. The constructor of the class takes the tag and stores it in uppercase.

In .NET code comparing objects for equality is done using the Equals and the GetHashCode methods of System.Object. I will override these to work with the nametag. Objects of this class can be stored in lists and array, who can be sorted. The sorting order is determined by the implementation of the IComparable interface. The TaggedObject provides an implementation of Icomparable and its only method CompareTo to sort TaggedObject's on the tagstring

Now I have a bases class which manages the tag and gives all object based on this class the desired comparison behavior. The next step is to build a class which will wrap a cargo object together with this name tag. The TagAndObject class needs a private variable to hold the object and I will give it two constructors, one which takes the object and will extract the nametag using the ToString method of the object and one which accepts an explicit name in the second parameter. Both constructors use the base class to set the nametag. Again I have overridden the ToString method, it will use the ToString method of the cargo object to obtain a string representation.

The final step is to build a class which wraps up a list of these TagAndObject objects. I will derive this class from ArrayList and it will implement the IEnumerator interface. Objects of a class which implement this interface can be used where .NET expects a collection, like in a foreach loop. Implementing this interface mainly consists of managing an index which points to the current item. I will add a FindItem method, this will find an item in the list based on a nametag passed and will return the wrapped up cargo object.

The ArrayList class has an Add method. A new overloaded version of this method is added to the class, it accepts an object and a name tag as parameter, wraps them up in a TaggedObject and adds this object to the arraylist. The default Add method of the ArrayList class is overriden. It checks the type of the object to add, if it is not already TagAndObject it will call the overloaded Add method to do the wrapup.

Exposing .net classes via COM interop

Now I have some handy base classes at hand I can build a base class for a connectable COM automation object. This class will implement the IconnectionPointcontainer interface and provide an easy way for clients to hand eventsinks to objects based on this class.

So far all base classes I built were in the GekkoLibrary and placed in the namespace Gekko. The bases classes for automation will be in the same library. I will place them in the namespace Gekko.Automation. Namespaces are a very clear and easy way to organize classes. 

Automation base classes

Connectable automation objects work like this :

1. The class should provide an implementation of the IconnectionPointContainer and manage connectionpoints. Clients will connect to the object by passing it an eventsink interface. 
2. There is a connectionpoint for every type of interface. The actual connections herein are grouped in a connections collection. So the eventsinks to sink events are organized in a collection of collections.
3. Every connection consists of a client-supplied eventsink interface and an identifying cookie.

To realize this I have built 5 base classes

1. hResults. All API calls in COM return a hResult value reporting the (amount of) success. The static hResults class groups the most common hResult constants.
2. AutoObjectWithEvents. Implements the COM interfaces IconnectionPointContainer and IenumConnectionPoints. This is the base class to build connectable automation objects.
3. ConnectionPoint. Implements the COM interfaces IConnectionPoint and IenumConnections. Connectionpoint objects are created by methods of the AutoObjectwithEvents class.
4. Connection. Implements the actual connection between a client and the connectable object. It wraps up the client's eventsink and it's associated cookie. Connection objects are created by clients connecting to the automation object.
5. ConnectionFactory. The actual connections are implemented by the client, the connectable object cannot create connection objects by itself. ConnectionFactory objects are created by the client. The factory should follow the signature of this abstract ConnectionFactory class. The client does this by descending from this class and providing an implementation of the class's only method InitConnection.

hResults class

The hResults class is quite straightforward, at this moment it only supports the S_OK and S_FALSE constants, enough to recognize success and failure of a COM API call.

AutoObjectWithEvents class

This class will be the baseclass for all objects who want to expose (parts of) their functionality as a COM connectable object. Objects of this class manage a collection of ConnectionPoints. I will use an object of the TaggedObjectList base class to store and manipulate these. The public methods FindSink and CreateConnectionPoint can rely on this object-list to do the real work