Register COM Component

Self-Registering Components

When the MATLAB^® Compiler SDK™ product creates a component, it automatically generates a binary file called a type library. As a final step of the build, this file is bound with the resulting DLL as a resource.

MATLAB Compiler SDK COM components are all self-registering. A self-registering component contains all the necessary code to add or remove a full description of itself to or from the system registry. The mwregsvr utility, distributed with the MATLAB Runtime, registers self-registering DLLs.

A component installed onto a particular machine must be registered with mwregsvr. If you move a component into a different folder on the same machine, you must repeat the registration process. When deleting a component from a specific machine, first unregister it to ensure that the registry does not retain erroneous information.

Tip

The mwregsvr utility invokes a process that is similar to regsvr32.exe, except that mwregsvr does not require interaction with a user at the console. The regsvr32.exe process belongs to the Windows^® OS and is used to register dynamic link libraries and Microsoft^® ActiveX^® controls in the registry. This program is important for the stable and secure running of your computer and should not be terminated. You must specify the full path of the component when calling mwregsvr, or make the call from the folder in which the component resides. You can use regsvr32.exe as an alternative to mwregsvr to register your library.

Register Add-Ins and COM Components

Note

COM components are used in both MATLAB Compiler™ and MATLAB Compiler SDK, therefore some of the instructions relating to building and packaging COM components and add-ins can be shared between products.

When you create your COM component, it is registered in either HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER, based on your log-in privileges.

If you find you need to change your run-time permissions due to security standards imposed by Microsoft or your installation, you can do one of the following before deploying your COM component or add-in:

Log on as administrator before running your COM component or add-in
Run the following mwregsvr command prior to running your COM component or add-in, as follows:
```
mwregsvr [/u] [/s] [/useronly] project_name.dll 
```
where:
- /u allows any user to unregister a COM component or add-in for this server
- /s runs this command silently, generating no messages. This is helpful for use in silent installations.
- /useronly allows only the currently logged-in user to run the COM component or add-in on this server

Caution

If your COM component is registered in the USER hive, it will not be visible to Windows Vista^® or Windows 7 users running as administrator on systems with UAC (User Access Control) enabled.

If you register a component to the USER hive under Windows 7 or Windows Vista, your COM component may fail to load when running with elevated (administrator) privileges.

If this occurs, do the following to re-register the component to the LOCAL MACHINE hive:

Unregister the component with this command:
```
mwregsvr /u /useronly my_dll.dll
```
Reregister the component to the LOCAL MACHINE hive with this command:
```
mwregsvr my_dll.dll
```

Globally Unique Identifier

Information is stored in the registry as keys with one or more associated named values. The keys themselves have values of primarily two types: readable strings and GUIDs. (GUID is an acronym for Globally Unique Identifier, a 128-bit integer guaranteed always to be unique.)

The compiler automatically generates GUIDs for COM classes, interfaces, and type libraries that are defined within a component at build time, and codes these keys into the component's self-registration code.

The interface to the system registry is folder based. COM-related information is stored under a top-level key called HKEY_CLASSES_ROOT. Under HKEY_CLASSES_ROOT are several other keys under which the compiler writes component information.

Caution

Do not delete the DLL-file in your project's src folder between builds. Doing so causes the GUIDs to be regenerated on the subsequent build. To preserve an older version of the DLL, register it on your system before rebuilding your project.

See the following table for a list of the keys and their definitions.

Key	Definition
`HKEY_CLASSES_ROOT\CLSID`	Information about COM classes on the system. Each component creates a new key under `HKEY_CLASSES_ROOT\CLSID` for each of its COM classes. The key created has a value of the GUID that has been assigned the class and contains several subkeys with information about the class.
`HKEY_CLASSES_ROOT\Interface`	Information about COM interfaces on the system. Each component creates a new key under `HKEY_CLASSES_ROOT\Interface` for each interface it defines. This key has the value of the GUID assigned to the interface and contains subkeys with information about the interface.
`HKEY_CLASSES_ROOT\TypeLib`	Information about type libraries on the system. Each component creates a key for its type library with the value of the GUID assigned to it. Under this key a new key is created for each version of the type library. Therefore, new versions of type libraries with the same name reuse the original GUID but create a new subkey for the new version.
`HKEY_CLASSES_ROOT\<ProgID>, HKEY_CLASSES_ROOT\<VerIndProgID>`	These two keys are created for the component's Program ID and Version Independent Program ID. These keys are constructed from strings of the following forms: `component-name.class-name` `component-name.class-name version-number` These keys are useful for creating a class instance from the component and class names instead of the GUIDs.

Versioning

MATLAB Compiler SDK components support a simple versioning mechanism designed to make building and deploying multiple versions of the same component easy to implement. The version number of a component appears as part of the DLL name, as well as part of the version-dependent ID in the system registry.

When a component is created, you can specify a version number. (The default is 1.0.) During the development of a specific version of a component, the version number should be kept constant. When this is done, the MATLAB Compiler SDK product, in certain cases, reuses type library, class, and interface GUIDs for each subsequent build of the component. This avoids the creation of an excessive number of registry keys for the same component during multiple builds, as occurs if new GUIDs are generated for each build.

When a new version number is introduced, MATLAB Compiler SDK generates new class and interface GUIDs so that the system recognizes them as distinct from previous versions, even if the class name is the same. Therefore, once you deploy a built component, use a new version number for any changes made to the component. This ensures that after you deploy the new component, it is easy to manage the two versions.

MATLAB Compiler SDK implements the versioning rules for a specific component name, class name, and version number by querying the system registry for an existing component with the same name:

If an existing component has the same version, it uses the GUID of the existing component's type library. If the name of the new class matches the previous version, it reuses the class and interface GUIDs. If the class names do not match, it generates new GUIDs for the new class and interface.
If it finds an existing component with a different version, it uses the existing type library GUID and creates a new subkey for the new version number. It generates new GUIDs for the new class and interface.
If it does not find an existing component of the specified name, it generates new GUIDs for the component's type library, class, and interface.