How to migrate ArcGIS 9.3 Desktop and Engine stand-alone applications to ArcGIS 10

Summary This topic explains how to migrate ArcGIS Desktop and Engine applications built in ArcGIS 9.3 to ArcGIS 10. It covers migration situations for applications built using the License Control as well as the ESRI.ArcGIS.esriSystem.AOInitialize class. ArcGIS Desktop and Engine applications created in 9.3 require a recompile against 10 assemblies.

In this topic

Install ArcGIS 10 Desktop or Engine Runtime

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

Install the ArcGIS 10 ArcObjects .NET SDK

At ArcGIS 10, you must install the ArcGIS 10 ArcObjects .NET software development kit (SDK) to develop .NET-based Desktop or Engine applications. This was not explicitly required at 9.3.
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

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 applications 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

Reference ESRI.ArcGIS.ADF.Local assembly
At ArcGIS 10, the functionality of the ESRI.ArcGIS.ADF assembly has been divided into multiple assemblies to separate development tasks performed by ArcGIS Server developers from ArcGIS Engine and ArcGIS Desktop developers. To have Desktop or Engine applications that were created in ArcGIS 9.3 work in the 10 architecture, perform the following two 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.

Reference AxControls if using ESRI Controls

At version 9.2, the separate assemblies delivered for each individual control (AxMapControl, AxTOCControl, and so one) were deprecated. At version 10 these assemblies have been removed. If your application uses ESRI Controls and make use of any of the individual control assemblies, you will need to update these references to the AxControls assembly by taking the following steps:
  1. Remove the references to any of the original assemblies for individual controls (AxMapControl, AxTOCControl, and so on).
  2. Add a reference to the ESRI.ArcGIS.AxControls assembly.

Set ESRI assemblies Specific Version property

To have a successful 10 compile of a migrated ArcGIS 9.3 Visual Studio development project, confirm that all ESRI assemblies have the Specific Version property set to false. To do this, follow these steps:
  1. Select the ESRI assemblies in Visual Studio Solution Explorer and right-click. The Properties dialog box opens.
  2. Set the Specific Version property to false as shown in the following screen shot:
The following Visual Studio 2008 error is an example compiler error that 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\MapControlApplication\bin\Debug\MapControlApplication.exe". Could not load file or assembly 'ESRI.ArcGIS.Carto, Version=9.3.0.1770, Culture=neutral, PublicKeyToken=8fc3cc631e44ad86' or one of its dependencies. The system cannot find the file specified.

Platform CPU target changes

At ArcGIS 10, developers who make ArcObjects executable applications should confirm that the platform target is set to x86 if the project references any ESRI assemblies with the processor architecture marked as x86. Otherwise, the .exe will fail to run on a 64-bit machine, since a 64-bit process refuses to load assemblies marked as x86 (32 bit). This was not necessary prior ArcGIS 10, because ESRI PIAs were marked as MSIL (any central processing unit [CPU]) so they could be loaded to either 32- or 64-bit processes.

C#

To adjust the platform target CPU in C#, follow these steps:
  1. Open the Visual Studio project's properties.
  2. Click the Build tab and change the Platform target combo box option to x86 as shown in the following screen shot:

VB .NET

To adjust the platform target CPU in Visual Basic .NET (VB. NET), follow these steps:
  1. Open the Visual Studio project's properties.
  2. Click the Compile tab and click the Advanced Compile Options button. The Advanced Compiler Settings dialog box opens.
  3. Change the Target CPU combo box option to x86. See the following screen shot:

Possible error

The following screen shot is an example of an error that can occur if the platform target CPU is not set to x86 and the ArcObjects application attempts to execute on a 64-bit machine:

Deployment considerations

Prior to ArcGIS 10, ArcGIS Desktop developers who accessed the Windows Registry to create custom setup.exe programs often used the following:
  • 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
At ArcGIS 10, Desktop developers should use the following:
  • 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
Prior to ArcGIS 10, ArcGIS Engine developers who accessed the Windows Registry to create custom setup.exe programs often used the following:
  • 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
At ArcGIS 10, Engine developers should use the following:
  • 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
 

License initialization

In ArcGIS 9.3, license initialization is required for all stand-alone applications (.exe) before running an ArcObjects component. The application programming interfaces (APIs) that establish ArcGIS license checking are in the ESRI.ArcGIS.esriSystem.AoInitialize class. Traditionally, license checking is done by one of the following methods:
  • Explicitly—Writing AoInitialize code, usually using the ArcGIS License Initializer wizard. For developers using ESRI Visual Studio integrated development environment (IDE) tools, the ArcGIS License Initializer wizard was invoked by the Add ArcGIS License Checking command.
  • Implicitly—Placing a LicenseControl on a Windows Form control.

Runtime binding requirement

A new requirement at ArcGIS 10 is runtime binding. Runtime binding refers to locating the appropriate ArcGIS product installation of a stand-alone ArcGIS Desktop or Engine application before any ArcObjects code (including license initialization) is called. The APIs to establish runtime binding are in the ESRI.ArcGIS.RuntimeManager class in the ESRI.ArcGIS.Version assembly installed in the Global Assembly Cache (GAC) with any ArcGIS 10 runtime. When the ArcObjects .NET SDK is installed, the ESRI.ArcGIS.Version assembly is installed by default in the C:\Program Files\ArcGIS\DeveloperKit10.0\DotNet folder for you to add as a reference in the Visual Studio IDE.

Migrating an ArcGIS 9.3 application to 10 using the LicenseControl

To migrate ArcGIS 9.3 Desktop and Engine applications that were built using the License Control to 10, perform the following steps:
  1. Install the ArcObjects .NET SDK.
  2. Upgrade Visual Studio 2003 and 2005 projects to Visual Studio 2008.
  3. Confirm that all ESRI assemblies have their Project Properties Specific Version set to false.
  4. Add the ESRI.ArcGIS.Version assembly to the project.
  5. Add the ESRI.ArcGIS.ADF.Local assembly to the project. 
  6. Add the following line of code inside before any other ArcObjects code is used:
[C#] 
//Insert this line before the Application.Run in the static void Main() method.
ESRI.ArcGIS.RuntimeManager.Bind(ESRI.ArcGIS.ProductCode.Engine);
[VB.NET] 
'Insert this line before the InitializeComponent() method in Public Sub New().
ESRI.ArcGIS.RuntimeManager.Bind(ESRI.ArcGIS.ProductCode.Engine)
If the RuntimeManager.Bind call is not placed in the correct location, i.e. before any other ArcObjects code is used, the following runtime error message will result:

Migrating an ArcGIS 9.3 application to 10 using the ESRI.ArcGIS.esriSystem.AoInitialize class

Runtime binding must also be performed on code written using the ESRI.ArcGIS.esriSystem.IAoInitialize class. There are two scenarios when this would be done: with code that was written manually, and with code that was generated by the ArcGIS License Initializer Wizard. Steps for both are shown in the following subsections.

Code written manually

To migrate manually written code from an ArcGIS 9.3 application to 10 using the ESRI.ArcGIS.esriSystem.AoInitialize class, perform the following steps:
  1. Install the ArcObjects .NET SDK.
  2. Upgrade Visual Studio 2003 and 2005 projects to Visual Studio 2008.
  3. Confirm that all ESRI assemblies have their Project Properties Specific Version set to false.
  4. Add the ESRI.ArcGIS.Version assembly to the project.
  5. Add the following line of code inside before any other ArcObjects code is used:
[C#] 
ESRI.ArcGIS.RuntimeManager.Bind(ESRI.ArcGIS.ProductCode.Engine);
[VB.NET] 
ESRI.ArcGIS.RuntimeManager.Bind(ESRI.ArcGIS.ProductCode.Engine)

Code generated by the ArcGIS License Initializer wizard

To migrate ArcGIS 9.3 Desktop and Engine applications that were built using the AoInitialize class (and that were constructed using the ArcGIS License Initializer Wizard) to 10, perform the following steps:
  1. Install the ArcObjects .NET SDK.
  2. Upgrade Visual Studio 2003 and 2005 projects to Visual Studio 2008.
  3. Confirm that all ESRI assemblies have their Project Properties Specific Version set to false.
  4. Add the ESRI.ArcGIS.Version assembly to the project.
  5. Add the ESRI.ArcGIS.ADF.Local assembly to the project.
  6. Run the ArcGIS License Initializer wizard, which is invoked by the Add ArcGIS License Checking command in Visual Studio. See the following screen shot:

Although the ArcGIS License Initializer was run in the ArcGIS 9.3 development project, the ArcGIS License Initializer needs to be run again when migrating to 10, since some of the code that the ArcGIS License Initializer generated has changed. See the following screen shot:
  1. Add the following line of code inside before any other ArcObjects code is used:
[C#] 
//Insert this line before the Application.Run in the static void Main() method. 
ESRI.ArcGIS.RuntimeManager.Bind(ESRI.ArcGIS.ProductCode.Engine);
[VB.NET] 
'Insert this line first in MyApplication_Startup () event handler in ApplicationEvents.vb file.
ESRI.ArcGIS.RuntimeManager.Bind(ESRI.ArcGIS.ProductCode.Engine)
If the RuntimeManager.Bind call is not placed in the correct location, i.e. before any other ArcObjects code is used, the following runtime error message will result:


See Also:

Migrating VBA customizations to ArcGIS 10
Migrating ArcGIS 9.3 Desktop and Engine custom components to ArcGIS 10



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