Migrating ArcGIS 9.3.x and 10 Desktop and Engine custom components to ArcGIS 10.1

Summary
This topic explains what's required to migrate custom components from ArcGIS 9.3.x or 10 to ArcGIS 10.1. Custom components created in 9.3.x or 10 require a recompile against the 10.1 assemblies.

Installing ArcGIS for Desktop or Engine 10.1

Before you can migrate ArcGIS 9.3 or 10 Desktop or Engine custom components, ArcGIS 10.1 for Desktop (Basic, Standard, or Advanced) or ArcGIS 10.1 Engine must be installed. 

Installing the ArcObjects SDK for the Microsoft .NET Framework

Unlike developing custom components in ArcGIS 9.3 (where the software development kit [SDK] is not explicitly required), starting at ArcGIS 10, you must have the ArcObjects .NET SDK installed to develop .NET-based custom components.
Before you can install the ArcObjects SDK for the Microsoft .NET Framework, make sure Visual Studio 2010 is installed on your machine. To build .NET applications with ArcGIS for Desktop or Engine, the Microsoft .NET Framework 3.5.1 is required.

Recompiling

At ArcGIS 10.1, as with ArcGIS 10, Esri no longer provides policy files. Consequently, all ArcGIS 9.3.x and earlier development projects ported to ArcGIS 10.1 must be recompiled. Each ArcGIS executable includes a configuration file that redirects the assemblies to the newer version. However, this is available for convenience to assist in testing and migration purposes. Esri recommends that you recompile, test, and certify your applications for each ArcGIS release.   

Upgrading Visual Studio projects

For ArcGIS Desktop and Engine custom components created using Visual Studio 2003, 2005, or 2008, you need to open the projects in Visual Studio 2010 and run the Microsoft upgrade wizard. Upgrading Visual Studio projects enables you to take advantage of all the features of the ArcGIS 10.1 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

Setting Start external program in Visual Studio

The default install location of ArcGIS for Desktop has changed at 10.1 and is located under <install location>\ArcGIS\Desktop10.1, as opposed to ArcGIS 9.3.x: <install location>\ArcGIS and ArcGIS 10: <install location>\ArcGIS\Desktop10.0.  
For an ArcGIS for Desktop developer to debug custom components with ArcMap (or any other ArcGIS application), they need to change the Start external program option under Start Action on the Debug tab on the project Properties dialog box in Visual Studio, and point it to the correct location of the application they want to debug. ArcGIS Engine developers who create custom components for another application need to point their Start external program to that application.
Pointing to an incorrect application location in Visual Studio results in an error message as shown in the following dialog box:

 
To change the location of the external program, right-click the project and select properties. In the project properties, select Debug and change the external program path to its new location. The following screen shot shows the default setting of the Start external program option in ArcGIS 10.1:

Changes to the ESRI.ArcGIS.ADF assembly (9.3.x only)

Starting at ArcGIS 10, the functionality of the ESRI.ArcGIS.ADF assembly was split into multiple assemblies to separate development tasks performed by ArcGIS Server from ArcGIS Engine and ArcGIS for Desktop developers. To allow custom components that use this assembly created in ArcGIS 9.3.x to work in the 10.x 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 corrects most compile time errors and warnings. See the following screen shot that highlights the ESRI.ArcGIS.ADF.Local assembly:


When the ArcGIS 10.1 ArcObjects .NET SDK is installed, the default installation location of the ESRI.ArcGIS.ADF.Local assembly is
<install location>\ArcGIS\DeveloperKit10.1\DotNet\ESRI.ArcGIS.ADF.Local.dll.
The following is a list of some of the Visual Studio compiler errors and warnings that can occur when an ArcObjects development project created in ArcGIS 9.3.x that does not include the ESRI.ArcGIS.ADF.Local assembly, is ported to ArcGIS 10.1:
  • 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. 

Setting Esri assemblies Specific Version property

To have a successful compile of a migrated ArcGIS 9.3.x or 10 Visual Studio development project, confirm that all Esri assemblies have the Specific Version property set to false. Visual Studio automatically uses the new version of the assembly to compile. To do this, follow these steps:
  1. Select an Esri assembly in the Visual Studio Solution Explorer. Right-click the assembly and select Properties. The Properties dialog box appears. 
  2. Set the Specific Version property to False as shown in the following screen shot:

 
The following Visual Studio example compiler error can occur when an ArcObjects development project created in ArcGIS 9.3.x that does not have the Esri assembly Specific Version property set to False, is ported to ArcGIS 10.1:
  • 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.

Updating component category registration (9.3.x only)

Since the first release of ArcGIS, developers have been able to extend ArcGIS applications though numerous Esri-defined extensibility points based on the Microsoft Component Object Model (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, or C++. For these components to be loaded in the application, components must also be registered with the appropriate Esri-defined component category.
Starting at ArcGIS 10, ArcGIS applications no longer read components from the registry. Custom components still need to be registered as all COM components do; however, ArcGIS now uses Extensible Markup Language (XML) tables to store component associations instead. This more flexible and efficient pattern allows ArcGIS to map component activations to the version appropriate application. 
To properly register your custom component with ArcGIS, registration should be done using the Esri-provided ESRIRegAsm.exe utility. This utility replaces the standard Microsoft RegAsm.exe and RegSvr32.exe utilities. 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. ESRIRegAsm registers the component on the machine, then creates a configuration file (*.ecfg) in the appropriate folder for the product for which the component was registered. For example, an ArcGIS for Desktop customization would be located in the following area:
  • <Program Files>\Common Files\ArcGIS\Desktop10.1\Configuration\CATID
Because of this change in component category registration, simply compiling the solution is not sufficient to register your component with the system, and your component will not load when you debug your application. You can, however, call the ESRIRegAsm utility from your Visual Studio project at compile time. This can be done by editing the Visual Studio project file (.csproj or .vbproj) and modifying 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>
Add the preceding line of XML code just above the closing </Project> tag in the project's XML file. Specific arguments vary depending on the ArcGIS product for which the COM registration is occurring. For details on the possible command line arguments, see the previously mentioned ESRIRegAsm utility topic.
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 register your custom components in ArcGIS for Desktop and ArcGIS Engine, see How to register custom components for multiple products.
To use the ESRIRegAsm utility to register your ArcGIS for Desktop custom components at compile time (to more easily debug and test your components), follow these steps:
  1. In Visual Studio, right-click the project name in the Solution Explorer and select Unload Project as shown in the following screen shot:

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

     
  1. Add the following MSBuild code to your project. Place the code at the bottom of your project file above the closing project tag.
[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 the following screen shot that shows the code in the project file:

 
  1. Right-click the project name in the Solution Explorer, select Reload Project, then save the project.  
  2. Build and run the project to debug your application.

Deployment considerations

Before ArcGIS 10, ArcGIS Desktop developers who accessed the Windows Registry to create custom setup.exe programs often used the following:
 
  • Default installation location of ArcGIS Desktop:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcInfo\Desktop\8.0
InstallDir
  • Version number of the installed ArcGIS Desktop:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcInfo\Desktop\8.0
RealVersion
At ArcGIS 10.1, Desktop developers should use the following:
  • Default installation location of ArcGIS for Desktop:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Desktop10.1
InstallDir
  • Version number of the installed ArcGIS for Desktop:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Desktop10.1
RealVersion
Before ArcGIS 10, ArcGIS Engine developers who accessed the Windows Registry to create custom setup.exe programs often used the following:
  • Default installation location of ArcGIS Engine:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcGIS Engine Runtime
InstallDir
  • Version number of the installed ArcGIS Engine:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcGIS Engine Runtime
RealVersion
At ArcGIS 10, Engine developers should use the following:
  • Default installation location of ArcGIS Engine:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Engine10.1
InstallDir
  • Version number of the installed ArcGIS Engine:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Engine10.1
RealVersion


See Also:

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



Development licensing Deployment licensing
ArcGIS for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced ArcGIS for Desktop Advanced
Engine Developer Kit Engine