Registering ACOMDLL

Registering EA AddIns - my understanding of how EA and Windows work

There seems to be a lot of confusion with EA installers and the associated registration of AddIn Dll's. Although I would like to think that there are clear rules and that breaking them would provide clear error messages this doesn't appear to be the case. In fact, I have seen DLL libraries registered in ways I wouldn't expected but Windows seems to be kind and employs techniques when looking for a class library that means that in most cases the class can be found!!

On this page I consolidate my understanding of how COM objects work within the context of the EA AddIns; it is this information that has been used with my EAInstallation Inspector.

Terms

This isn't a formal document however I realise that I may use some terms that have specific meaning:

  • DLL - is the file containing your class library
  • Assembly - is the information that is defined when the DLL is created and includes the class name, version,

In this document I may use the term Library to refere in a general sense to some or all of the above

  • HKCR - abbreviation for HKEY_CLASSES_ROOT - section of registry store Class Roots
  • HKCU - abbreviation for HKEY_CURRENT_USER - section of registry store Current User information
  • HKLM - abbreviation for HKEY_LOCAL_MACHINE - section of registry stores Local Machine (all users) information
  • CLSID - abbreviation for ClassID which is a GUID used to reference class information

Quick overview

Before providing here is a quick overview of the primary registry keys used with EA AddIns. A specific AddIn may have additional keys of its own but that is out of scope for this document

EA Specific keys

  • EA finds out about AddIns by reading keys in one of 2 specific areeas in the Registry which defines the class containing EA API defined interface methods
    • HKCR\SOFTWARE\Sparx Systems\EAAddins\AddIn name
    • HKLM\SOFTWARE\Wow64332Node\Sparx Systems\EAAddins\AddIn name

AddIn DLL

  • The AddIn DLL must be a 32-bit DLL and registered for either

Installed as Current User

In this case keys will be located in

  • HKCU\SOFTWARE\Classes\classname\ - the classname entry has a subkey referercing the CLSID
  • HKCU\SOFTWARE\Classes\CLSID - an entry for the DLL CLSID with subkeys containing details about the DLL
  • HKCU\SOFTWARE\Software\Classes\WOW6432Node\CLSID - and entry for the DLL CLSID with subkeys containing details about the DLL

Installed for Local Machine

  • HKLM\SOFTWARE\Classes\classname\- the classname entry has a subkey referercing the CLSID
  • HKLM\SOFTWARE\Classes\CLSID - an entry for the DLL CLSID with subkeys containing details about the DLL
  • HKLM\SOFTWARE\Classes\WOW6432Node\CLSID - an entry for the DLL CLSID with subkeys containing details about the DLL

All installs

When registering using RegAsm additional entries will be made in HKCR relating to the Active DLL.

  • HKCR\classname\CLSID - provides a Subkey with the CLSID
  • HKCR\WOW6432Node\CLSID - an entry for the DLL CLSID with subkeys containing details about the DLL that is active

NOTE: If the DLL is registered for both Local Machine and Current User, then the Current User registration has precendence and will be the CLSID set in HKCR

EA Addin references

For EA to load an AddIn it must be able to find it during its startup initialisation phase. With that information it will dynamically load your library and assuming all is well your AddIn will be available within EA.

EA finds out about AddIns by reading specified keys in the Windows Registry. So prior to running EA these keys must be defined by YOU. The keys may be located in

  • HKEY_CURRENT_USER\Software\Sparx Systems\EAAddins - addin installed for current user only
  • HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Sparx Systems\EAAddins - addin installed for all users on local machine

Adding a key to this area which has a default value set to your addin class does the job. So during initialisation (EA startup) EA reads these keys and will attempt to load the specified class.

Below is an example Addin Entry

With that value set EA will attempt to load the class, which in our example is TestAddIn.TestAddIn. NOTE: It is legal to have multiple EA Addin entries that point to the same AddIn class - e.g.

Not sure why anybody would want to, but EA doesn't seem to complain.

Class registration

The referenced addin class MUST be registered before EA can dynamically load the addin class. This may be done in one of several ways:

  • During development some tools may register your DLL. For example, when using Visual Studio Compile settings page there is a checkbox to automatically "Register for COM interop"
  • During installation, it would be expected that the installer has been configured to set the relevant keys
  • Manually using tools such as RegAsm (see below)

The Windows Registry is a database with a lot of information about the current system - see overview of windows registry

Some of the information within the registry details DLLs/Assemblies/libraries can be used by any application that knows about them. In the case of a DLL library the information within the registry will include:

  • All the public classes exposed by the library
  • Full file location of the DLL
  • Assembly details for the DLL, as set by the developer

A library may be registered for the current user or for any user on the local machine, and depending on the choice keys will be placed in different areas of the registry.

The DLL library may have been created as a 32-bit or 64-bit assembly. Each type will use different:

  • tools to register the library
  • key locations in the registry.

Note: EA can be a 32-bit or 64-bit application and hence AddIn DLL's must be built to be compatible; the keys will stored in areas reserved for 32-bit or 64-bit libraries.

Illustration of COM keys

If we take an example library (TestAddIn.dll) with 1 public class TestAddIn.TestAddIn. When registered there will be a registry key entry normally under CLASSES_ROOT (HKCR) whose name is TestAddIn.TestAddIn. That key will have a sub-key called CLSID whose default value which is a GUID.

Also there will be additional entries relating to different scenarios depending on how the library has been registered:

  • Local machine installed only - the entry under HKCR will be that defined in HKLM
  • Current user installed only - the entry under HKCR will be that defined in HKCU
  • Local machine and current machine installed only - the entry under HKCR will be that defined in HKCU

In the case that the current user version is removed and a local machine entry exists then the value in HKCR will change to reflect the value in HKLM

Class information

In terms of EA it is the key with the specified class name that is located in HKCR e.g. TestAddIn.TestAddIn that will provide the information relating to the registered class. Use is made of a CLSID to get more details on the library. For our 32-bit EA AddIn library there are 2 locations that we can inspect. For libraries registered for:

  • Current User - inspect HKCU\Software\Wow6432Node\Classes\CLSID
  • Local Machine - inspect HKLM\Software\Wow6432Node\Classes\CLSID

The default value should be our class name!

Subkey information

Within this key more information is contained in sub-keys as follows:

  • Implemented Categories - doesn't appear to have any values for AddIn related classes
  • InprocSever32
    • Assembly
    • Class
    • CodeBase - location of the DLL file
    • RuntimeVersion .Net framework

This subkey will also have a subkey whose name is the Assembly version number - and contains copies of the information in the parent

  • ProgID - the default value identifies the class name for the addin. Note that, unlike a CLSID, the ProgID is not guaranteed to be globally unique. In fact, Windows allows multiple version of a class to be registered so that application using an old version of a library will not be affect if a new version is installed. HOWEVER, if the class is being dynamically loaded, as is done by EA, it will access the library via the Class Name and there will only be ONE entry under the classes root (HKCR) and this will be the version that was LAST registered and this MAY NOT be the latest version of the library!!

Registering a DLL library

As indicated above this may be done automatically or as part of an installers work. However, during development its likely that this will be done using tools tasked with registering COM libraries. BTW: I am sure you can add keys manually to the registry and it should work - perhaps I'll try one day just to prove there is mysterious magic going on behind the scenes.

The tool I use is called Regasm and is supplied as part of the Microsoft .NET framework. It will register the library for Local Machine use (HKLM) and hence requires to be run within a cmd window that has local admin rights.

Below are some examples of using Regasm to register DLL, and NOTE different version of RegAsm exists for different frameworks.

For 32-bit DLL: .NET3.5 

"C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\RegAsm.exe" ".\bin\Debug\MyAddIn.dll" /codebase

.NET4 

C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe  ".\bin\Debug\MyAddIn.dll" /codebase /verbose

For 64-bit DLL: 

C:\WINDOWS\Microsoft.NET\Framework64\v4.0.30319\RegAsm.exe  ".\bin\x64\Debug\E002_ASimpleEAMenu.dll" /codebase

To register a DLL for the current user only (and not require local admin rights) see Non Admin Registration pages.