English

How To: Register Legacy Components with ArcGIS 10

Summary

The following article provides ArcGIS Developers with instructions on how to register legacy components with 10.

Note:
Legacy components in this case are components that were built at a previous release of ArcGIS.


Warning:
The following steps are provided from migration purposes only! ESRI recommends that developer recompile and redeploy their customizations for each release.

ESRI does not provide any support for the following workflow.

It is the responsibility of the developer to thoroughly test and verify that the component works correctly in the new release.

If the following does not work, the component must be recompiled in a supported development environment.


At previous releases of ArcGIS, developers would create components for ArcGIS and register these components within particular Component Object Model (COM) Categories based on the type of customization. When an ArcGIS application started up, it would load appropriate components based on these categories. Since these custom components were registered outside of an ArcGIS setup, they would not be removed when ArcGIS was uninstalled. Thus, when the end user would upgrade to the next release the components would automatically be loaded by ArcGIS.

Many developers would leverage this functionality to create customizations that would span multiple versions. ESRI does not support or recommend this approach and recommends that all customizations are recompiled and fully tested for each release of the product. Functionality can change from release to release, and it is important for a developer to recertify and redeploy a custom solution to verify that it works at the newest release of the software. It is important for developers to review the design and implementation of their customizations to ensure they leverage the capabilities of the newer releases.

At version 10, ArcGIS no longer reads the system registry to load custom components. Components registered into categories using RegSvr32.exe (for native code) and RegAsm.exe (for managed code), or by using any other means of registration (such as using .reg files), will no longer be loaded by ArcGIS. Instead, developers should use ESRIRegAsm.exe to register their components. This utility handles the registration of the .dll and the category information by creating a configuration file (.ecfg). The configuration file is read by an ArcGIS application at runtime to load custom components. This configuration must reside in the appropriate product and version configuration folder. For example, ArcGIS 10 Desktop customizations reside in the following location:

%CommonProgramFiles%\ArcGIS\Desktop10.0\Configuration\CATID

ESRI understands that many customers have legacy components that have always worked from release to release.

The following steps provide instructions on how to register legacy components with ArcGIS 10 so that customers can continue to use these components during the migration.

Procedure

There are two types of DLLs that are registered with ArcGIS: those that register themselves with component categories (such as C++ or .NET) or those that do not (such as VB6 DLLs). For both of these, a configuration file (.ecfg) must be created for ArcGIS to read the customization.

This configuration file can then be deployed onto the machine by way of the setup program. The deployment of the configuration file can also be within a patch.

Note:
In all of the following workflows, the DLL must be registered with the system. ESRIRegAsm.exe will handle this on the developer's machine. For deployment, the setup program must register the component on its own. This procedure is specifically for adding category registration.

  • If the component was written in a language that supports category registration, the component can be registered using ESRIRegAsm.exe. The example below shows how to register a DLL with ArcGIS Desktop.

    Code:
    %CommonProgramFiles%\ArcGIS\Bin\ESRIRegAsm /p:Desktop "C:\Program\MyDll.dll"

    Note:
    For .NET developers, ESRI no longer ships policy files with ArcGIS. Legacy components written in .NET should work with ArcGIS executables because they use an app.config file to redirect the assemblies to the appropriate version. Engine developers who rely on components need to create their own application configuration files for their executables.

  • If the DLL does not support category registration, such as customizations where registry scripts were used after registration to provide the category information, or if the developer used .reg files to register their components, developers can still leverage this method to register the category information.

    For example, below is a registry file that adds a custom ZoomIn command to the ESRI Mx Commands Category.

    Code:
    REGEDIT4
    ; Coclass: prjDisplay.ZoomIn
    ; CLSID: {FC7EC05F-6B1B-4A59-B8A2-37CE33738728}
    ; Component Category: ESRI Mx Commands
    {HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{FC7EC05F-6B1B-4A59-B8A2-37CE33738728}
    \Implemented Categories\{B56A7C42-83D4-11D2-A2E9-080009B6F22B}]


    The .reg file can be used directly by ESRIRegAsm to create an .ecfg file with the following syntax:

    Code:
    %CommonProgramFiles%\ArcGIS\Bin\ESRIRegAsm /p:Desktop "C:\Program\MyDll.dll" /f:"C:\Progam\myRegFile.reg"

  • If any other registration mechanism was used, the developer also has an option to create an .xml configuration file. This file can then be used in the ESRIRegAsm utility to create the .ecfg configuration file.

    For example, using the same command as above, the developer can create an XML file using Notepad.exe or using an XML Editor following the syntax below:

    Code:
    <Categories>
    <Category CATID="{B56A7C42-83D4-11D2-A2E9-080009B6F22B}">
    <Class CLSID="{FC7EC05F-6B1B-4A59-B8A2-37CE33738728}" />
    </Category>
    </Categories>


    Save this file as Config.xml. Run ESRI Regasm with the /f: paramenter and include the XML configuration file.

    Code:
    %CommonProgramFiles%\ArcGIS\Bin\ESRIRegAsm /p:Desktop "C:\Program\MyDll.dll" /f:"C:\Progam\Config.xml"