In order to be able to create managed types from COM applications the appropriate entries must be made in the Windows registry. The runtime ships with a registration utility called RegAsm for just this purpose. RegAsm reads the metadata within an assembly and adds the necessary entries to the registry so classic COM clients can create the NGWS classes transparently.
Once a class is registered, any classic COM client can use it as though the class were a COM class. The registration process is only done one time when the assembly is installed. The classes within the assembly are not COM creatable until they are actually registered.
Not all classes within an assembly are creatable from COM. In fact; an assembly does not need to have any creatable classes. Managed classes are considered co-creatable if the class is public and also has public default constructor (the default constructor has no arguments). Only creatable classes are registered when the RegAsm tool is run on an assembly. Public classes without a public default constructor are visible but not creatable. Abstract classes are also not creatable.
The ability to create a type from COM can be overridden with the ComRegisterAttribute. The attribute can be applied to an individual class or to an entire assembly to control whether creatable types within the assembly are registered. To allow the creatable types to be registered, set the attribute to true. To prevent creatable type from being registered, set the attribute to false. Setting the attribute to false on the assembly prevents the registrations of all creatable types within the assembly. Setting the attribute to false on a specific class prevents the registration of that specific class. Settings applied to an individual class override any assembly settings. Therefore, setting the attribute to false on the assembly and true on an individual class will cause only that class to be registered. Only classes that are COM creatable can be registered. The attribute cannot be used to make an otherwise non-creatable class creatable.
Having creatable classes has several implications:
Under some circumstances, classes that are not COM creatable may still be creatable from managed code. For example, a class may not be COM creatable because it has no default constructor but there be another constructor that would make it possible for another managed class to create the type. Under those circumstances, it’s possible for one type to return an instance of another non-creatable type as a return value or an out parameter provided that the non-creatable type is COM visible (see section 4.1.4.4.5).
RegAsm has the following command line syntax:
RegAsm AssemblyFile [/u] [/reg: RegFile] [/silent][/tlb: TlbFile]
The RegAsm utility registers or un-registers the creatable classes within the NGWS runtime assembly named AssemblyFile. RegAsm can also be used to generate a .reg file with the needed entries instead of actually making the changes to the registry.
Options:
/u - Causes RegAsm to unregister the public classes found in AssemblyFile as opposed to registering them. Omitting this option causes the public classes within the assembly to be registered.
/silent – Suppress all a console output.
/reg: RegFile - Generates a .reg file named RegFile for the assembly containing the registry entries that would have been added if this option had not been supplied. The registry is not changed when this option is used.
The .reg file can be used to update the registry on any machine by importing the file with the RegEdit tool. Note: The .reg does not contain any registry updates that may be made by any user defined register functions (see section 4.2.3 below).
/tlb: TlbFile - Generates and registers a type library with the name TlbFile describing the types found in the assembly. The type library can be used to provide type information to development tools like Visual Studio. Using the /tlb option has the same effect as running TlbExp then RegAsm.
Examples
RegAsm mytest.dll
Registers all public classes contained in mytest.dll.
RegAsm mytest.dll /reg: mytest.reg
Generates the file MyReg.reg that contains all the entries that would have been made to the registry if the /reg option had not been supplied. The registry is not updated.
RegAsm mytest.dll /tlb: mytest.tlb
Registers all public classes contained in mytest.dll. Generates and registers the type library mytest.tlb that contains definitions of all the public types defined in mytest.dll.
RegAsm mytest.dll /tlb: mytest.tlb /reg mytest.reg
Generates the type library mytest.tlb that contains definitions of all the public types defined in mytest.dll. Also generates the file MyReg.reg that contains all the entries that would have been made to the registry if the /reg option had not been supplied. The registry is not updated.
The RegAsm tool updates the registry with the following entries:
For each public, creatable class defined in the assembly the following entries are made
HKEY_CLASSES_ROOT\progid\CLSID {default} = {clsid of class} HKEY_CLASSES_ROOT\{clsid}\InProcServer32 {default} = mscoree.dll Class = name of class ThreadingModel = Both Assembly = Stringized assembly reference HKEY_CLASSES_ROOT\{clsid}\ProgId (default) = name of class HKEY_CLASSES_ROOT\{clsid}\TypeLib (default) = {tlbid}
If the /tlb is used, a type library is generated and the following additional entries are created in the registry.
HKEY_CLASSES_ROOT\Typelib\{tlbid}\x.y\ lcid\win32 (default) = location of type library file HKEY_CLASSES_ROOT\Typelib\{tlbid}\x.y\FLAGS (default) = 0
Where:
progid is the programmatic identifier assigned to the class.
clsid is the guid assigned to the class.
tlbid is the guid that identifies the type library.
x.y is the major and minor versions of the type library.
lcid is the locale id of the type library.
See section 4.1.4.3 above for details on how the progid, clsid and tlbid are generated.
The stringized assembly reference found under the InProcServe32 key is the string form of the name of the assembly containing the class. The string is obtained from AssemblyName.NameAsString and is used to locate and load the assembly when the class is being created. An example of a stringized assembly name is “FunnyFarm.BarnYard.Mammal, Ver=1.2.5.1”
Any COM creatable class (as defined above) can also have a registration and un-registration functions. The register function is called during the registration process so that application specific registration work can be done. The un-registration function is called when the type is unregistered. The method must be static and must take a single String parameter for the name of the registry key being updated. During registration and un-registration, the appropriate method is called with the registry key being updated (i.e., “HKEY_CLASSES_ROOT\CLSID\<clsid>”).
A class should have, at most, one register function and one unregister function. A method is identified as the register function with ComRegisterFunctionAttribute. A method is identified as the un-register function with ComUnregisterFunctionAttribute.
Register and Unregister functions are provided for backward compatibility only. Users are strongly discouraged from using these functions. In situations where they are necessary, the unregister function should be sure to “undo” whatever the register function did.