Migrating ArcGIS 9.3 Desktop and Engine custom components to ArcGIS 10

Summary This topic explains what's required to migrate custom components from ArcGIS 9.3 to ArcGIS 10. The custom components include ArcGIS Desktop extensions, ArcGIS Desktop and Engine classes, and ArcGIS Desktop and Engine base classes. Custom components created in 9.3 require a recompile against the 10 assemblies.

In this topic

Install ArcGIS 10 Desktop or Engine Runtime

Before you can migrate ArcGIS 9.3 Desktop or Engine custom components, ArcGIS 10 Desktop (ArcView, ArcEditor, or ArcInfo) or ArcGIS 10 Engine Runtime must be installed. 

Install the ArcGIS 10 ArcObjects .NET SDK

Unlike developing custom components in ArcGIS 9.3 (where the software development kit [SDK] is not explicitly required), at ArcGIS 10, it is mandatory to have the ArcObjects 10 .NET SDK installed to develop .NET-based custom components.
Before you can install the ArcGIS 10 ArcObjects .NET SDK, the following software must be installed on your machine:
  • Microsoft .NET Framework 3.5.1
  • Visual Studio 2008 with Service Pack 1

Recompile projects

At ArcGIS 10, ESRI no longer provides policy files. Consequently, all ArcGIS 9.3 and earlier development projects ported to ArcGIS 10 must be recompiled.

Upgrade Visual Studio projects to 2008

For ArcGIS Desktop and Engine custom components created using Visual Studio 2003 or Visual Studio 2005, you need to open the projects in Visual Studio 2008 and run the Microsoft upgrade wizard. Upgrading Visual Studio projects to Visual Studio 2008 enables you to take advantage of all the features of the ArcGIS 10 ArcObjects .NET SDK including the following: 
  • Primary interop assemblies (PIAs)
  • Visual Studio integrated development environment (IDE) tools
  • F1 help from the Visual Studio code editor

Set Start external program in Visual Studio

The default install location of ArcGIS Desktop has changed at 10. The default root install folder for ArcGIS 9.3 is C:\Program Files\ArcGIS. The default root install folder for ArcGIS 10 is C:\Program Files\ArcGIS\Desktop10.0.
ArcGIS Desktop developers who debug custom components need to change the Start external program option under Start Action on the Debug tab of the project Properties dialog box in Visual Studio to point to the correct location of the ArcMap.exe application. ArcGIS Engine developers who create custom components for another application need to point their Start external program to that application.
Pointing to an incorrect ArcMap.exe location in Visual Studio results in the following error message:

 
In ArcGIS 10, the default installation folder for the ArcMap.exe application is C:\Program Files\ArcGIS\Desktop10.0\bin\ArcMap.exe. The following screen shot shows the default setting of the Start external program option in ArcGIS 10:

 

Changes to the ESRI.ArcGIS.ADF assembly

At ArcGIS 10, the functionality of the previous ESRI.ArcGIS.ADF assembly has been split into multiple assemblies to separate development tasks performed by ArcGIS Server from ArcGIS Engine and ArcGIS Desktop developers. To have custom components that were created in ArcGIS 9.3 work in the 10 architecture, perform the following steps:
  1. Remove the reference to the original ESRI.ArcGIS.ADF assembly.
  2. Add a reference to the ESRI.ArcGIS.ADF.Local assembly.
This will correct most compile time errors and warnings. See the following screen shot:
 
When the ArcGIS 10 ArcObjects .NET SDK is installed, the default installation location of the ESRI.ArcGIS.ADF.Local assembly is
C:\Program Files\ArcGIS\DeveloperKit10.0\DotNet\ESRI.ArcGIS.ADF.Local.dll.
The following is a list of some of the Visual Studio 2008 compiler errors and warnings that can occur when an ArcObjects development project created in ArcGIS 9.3 that does not include the ESRI.ArcGIS.ADF.Local assembly is ported to ArcGIS 10:
  • Warning: Namespace or type specified in the Imports 'ESRI.ArcGIS.ADF.BaseClasses' doesn't contain any public member or cannot be found. Make sure the namespace or the type is defined and contains at least one public member. Make sure the imported element name doesn't use any aliases.
  • Warning: Namespace or type specified in the Imports 'ESRI.ArcGIS.ADF.CATIDs' doesn't contain any public member or cannot be found. Make sure the namespace or the type is defined and contains at least one public member. Make sure the imported element name doesn't use any aliases.
  • Error: Type 'BaseCommand' is not defined.
  • Error: Name 'MxCommands' is not declared.
  • Error: sub 'OnCreate' cannot be declared 'Overrides' because it does not override a sub in a base class.
  • Error: sub 'OnClick' cannot be declared 'Overrides' because it does not override a sub in a base class. 

Set ESRI assemblies Specific Version property

To have a successful 10 compile of a migrated ArcGIS 9.3 Visual Studio development project, make sure that all ESRI assemblies have the Specific Version property set to false. To do this, select all the ESRI assemblies in Visual Studio Solution Explorer and right-click. The Properties dialog box opens. Set the Specific Version property to false as shown in the following screen shot:
 
The following Visual Studio 2008 example compiler error can occur when an ArcObjects development project created in ArcGIS 9.3, that does not have the ESRI assembly Specific Version property set to false, is ported to ArcGIS 10:
  • Error: Cannot unregister assembly "C:\MyGISProjects\ArcMapClassLibrary_BaseCommand_Sample931\bin\Debug\ArcMapClassLibrary_BaseCommand_Sample931.dll". Could not load file or assembly 'ESRI.ArcGIS.ArcMapUI, Version=9.3.0.1770, Culture=neutral, PublicKeyToken=8fc3cc631e44ad86' or one of its dependencies. The system cannot find the file specified.

Register ArcGIS Desktop custom components

Once all compile errors have been addressed, the final step to test custom components being migrated to ArcGIS 10 is to correctly register the Component Object Model (COM) based assembly on your development machine. At ArcGIS 10, changes have been made to the COM registration process for ArcObjects. The following two options are available to ensure that ArcGIS Desktop custom components are registered correctly, enabling successful debugging and testing:

Add from file

The easiest option is to use the Add from file option on the Customize dialog box. Using this option, you can use the standard ArcMap interaction procedures, and the COM registration work is done behind the scenes.
To access Add from file, follow these steps:
  1. In ArcMap, click Customize and click Customize Mode. The Customize dialog box opens.
  2. Click the Commands tab and click Add from file. See the following screen shot:



    The Open dialog box opens.
  3. Select the .tlb file that is generated in the \Debug or \Release directory of the Visual Studio project and click Open. See the following screen shot:



    The Added Objects dialog box opens listing the available objects from your customizations. See the following screen shot:

  1. Click OK to return to the Customize dialog box.
  2. Select the appropriate category for the command that will be added to the ArcMap graphical user interface (GUI). See the following screen shot:

  3. Drag-and-drop the command onto the ArcMap GUI to test. 

ESRIRegAsm

If you would rather have your ArcGIS Desktop custom component automatically appear in the appropriate category, you can use the new ESRIRegAsm utility called from your Visual Studio project.
At ArcGIS 10, you still need to register ArcObjects custom components with the appropriate COM category. Since the first release of ArcGIS, developers have been able to extend ArcGIS applications though numerous ESRI-defined extensibility points based on Microsoft COM. To extend an ArcGIS application, developers must build component libraries consisting of component classes that implement one or more ESRI interfaces using any development environment or language that supports COM, such as C#, VB .NET, and C++. Components must also be registered with the appropriate ESRI-defined component category.
At ArcGIS 10, ArcGIS uses Extensible Markup Language (XML) tables to store component associations instead of relying on making changes to the Windows Registry COM component categories directly. This more flexible and efficient pattern allows ArcGIS to map component activations to the version-appropriate application.
At ArcGIS 10, product information must be supplied at registration using the new ESRI-provided ESRIRegAsm.exe, which replaces the standard Microsoft RegAsm.exe and RegSvr32.exe utilities. You need to call ESRIRegAsm.exe directly, supplying the appropriate product target as an argument. To learn more about the various arguments that ESRIRegAsm.exe uses, see ESRIRegAsm utility.
One way to use the ESRIRegAsm utility as part of debugging your Visual Studio 2008 project is to edit the Visual Studio project file (.csproj or .vbproj) and the XML that is associated with the MSBuild command. The following code is a sample of the necessary XML syntax for the MSBuild command:
[XML] 
<Target Name="BeforeClean">
  <Exec
    WorkingDirectory="$(CommonProgramFiles)\ArcGIS\bin"
    Command="esriRegasm.exe &quot;$(TargetPath)&quot; /p:Desktop /u /s"
    Condition="Exists('$(TargetPath)')"/>
</Target>
<Target Name="AfterBuild">
  <Exec
    WorkingDirectory="$(CommonProgramFiles)\ArcGIS\bin"
    Command="esriRegasm.exe &quot;$(TargetPath)&quot; /p:Desktop /s"/>
</Target>
See How to register custom components for multiple products to register your custom components in both ArcGIS Desktop and ArcGIS Engine.
Add this line of XML just above the closing </Project> tag in the project XML file. Specific arguments will vary depending on the ArcGIS 10 product for which the COM registration is occurring. See the ESRIRegAsm utility topic for details on the possible command line arguments.
If, as you view this topic in your Web browser, the XML for a single tag is broken over multiple lines (for readability), ensure that this formatting is not copied to your Visual Studio project file. The XML in the development project should have one XML tag per line, without embedded carriage returns.
To use the ESRIRegAsm utility to register your ArcGIS Desktop custom components (and to debug and test), follow these steps:
  1. In Visual Studio, right-click the project name in Solution Explorer, and select Unload Project as shown in the following screen shot:

     
  2. Right-click the project name in Solution Explorer and select Edit <project name> as shown in the following screen shot:

     
  3. At the end of the XML file, add the appropriate MSBuild lines, save the file, and close it. See the following screen shot:

     
  4. Right-click the project name in Solution Explorer, select Reload Project, then save the project. See the following screen shot:

     
  5. Build the project. The ESRIRegAsm utility is called in the Output window. See the following screen shot:

  6. To debug the application and automatically load the customization in the Customize dialog box, press F5. ArcMap starts.
  7. In ArcMap, select a .mxd file for testing, click Customize, and click Customize Mode. The Customize dialog box opens and the custom component is listed under Categories as shown in the following screen shot:

     

Deployment considerations

 
For ArcGIS Desktop developers who access the Windows Registry to create custom setup.exe programs, prior to ArcGIS 10 developers often used:
 
Default installation location of the ArcGIS Desktop product
Registry Hive
Key Value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcInfo\Desktop\8.0
InstallDir
 
Version number of the installed ArcGIS Desktop product
Registry Hive
Key Value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcInfo\Desktop\8.0
RealVersion
 
Starting with ArcGIS 10 developers should now use:
 
Default installation location of the ArcGIS Desktop product
Registry Hive
Key Value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Desktop10.0
InstallDir
 
Version number of the installed ArcGIS Desktop product
Registry Hive
Key Value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Desktop10.0
RealVersion
 
 
For ArcGIS Engine developers who access the Windows Registry to create custom setup.exe programs, prior to ArcGIS 10 developers often used:
 
Default installation location of the ArcGIS Engine product
Registry Hive
Key Value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcGIS Engine Runtime
InstallDir
 
Version number of the installed ArcGIS Engine product
Registry Hive
Key Value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcGIS Engine Runtime
RealVersion
 
Starting with ArcGIS 10 developers should now use:
 
Default installation location of the ArcGIS Engine product
Registry Hive
Key Value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Engine10.0
InstallDir
 
Version number of the installed ArcGIS Engine product
Registry Hive
Key Value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Engine10.0
RealVersion


See Also:

How to migrate ArcGIS 9.3 Desktop and Engine stand-alone applications to ArcGIS 10
Migrating VBA customizations to ArcGIS 10
ESRIRegAsm utility
How to register custom components for multiple products



Development licensing Deployment licensing
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo
Engine Developer Kit Engine Runtime