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

Summary
This topic explains how to migrate ArcGIS Desktop and Engine applications built in ArcGIS 9.3.x and 10 to ArcGIS 10.1. 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.x and 10 require a recompile against the 10.1 assemblies.

Installing ArcGIS 10.1 for Desktop or Engine

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

Installing the ArcGIS 10.1 ArcObjects .NET SDK

At ArcGIS 10.1, you must install the ArcGIS 10.1 ArcObjects .NET software development kit (SDK) to develop .NET-based Desktop or Engine applications. This was not explicitly required at 9.3.x.
Before you can install the ArcGIS 10.1 ArcObjects .NET SDK, you must have Visual Studio 2010 installed on your machine. To build .NET applications with ArcGIS for Desktop or Engine, the Microsoft .NET Framework 3.5.1 must be installed on the machine. ArcGIS for Desktop and Engine installs the .NET 3.5.1 framework if it is not already on the machine.

Recompiling

At ArcGIS 10.1, as with ArcGIS 10, Esri no longer provides policy files. Consequently, all ArcGIS 10 and earlier development projects ported to ArcGIS 10.1 must be recompiled.
To successfully recompile your code, you may need to perform some or all of the tasks outlined in the following sections.

Migrating an ArcGIS 9.3.x application to ArcGIS 10.1

The following discusses migrating an ArcGIS 9.3.x application to ArcGIS 10.1.

Upgrading Visual Studio projects

For ArcGIS Desktop and Engine applications created using Visual Studio 2003, Visual Studio 2005, or Visual Studio 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

Referencing ESRI.ArcGIS.ADF.Local assembly

At ArcGIS 10, the functionality of the ESRI.ArcGIS.ADF assembly was 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.x work in the 10.x 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 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 as follows:
  • C:\Program Files\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.

Referencing AxControls if using Esri controls

At ArcGIS 9.2, the separate assemblies delivered for each individual control (AxMapControl, AxTOCControl, and so on) were deprecated. At version 10, these assemblies were removed. If your application uses Esri controls and any of the individual control assemblies, you 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 (for example, AxMapControl, AxTOCControl, and so on).
  2. Add a reference to the ESRI.ArcGIS.AxControls assembly.

Setting Esri assemblies Specific Version property

To have a successful 10.1 compile of a migrated ArcGIS 9.3.x Visual Studio development project, confirm that all Esri assemblies have the Specific Version property set to false. To do this, follow these steps for each Esri assembly your project references:
  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:
  3. Repeat the steps for all Esri assemblies you have referenced.
The following Visual Studio error is an example of a compiler error that can occur when an ArcObjects development project created in ArcGIS 9.3 with Esri assembly Specific Version property set to true is ported to ArcGIS 10.1:
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.

Upgrading enumerations

At ArcGIS 10.1, changes have been made to the esriLicenseProductCode, esriProductCode, and esriLicenseExtensionCode enumerations. The changes have been made to the enumeration description, which requires you to make changes to your code when recompiling for 10.1.

Migrating an ArcGIS 10 application to ArcGIS 10.1

The following discusses migrating an ArcGIS 10 application to ArcGIS 10.1.

Upgrading Visual Studio projects

For ArcGIS Desktop and Engine applications created using Visual Studio 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: 
  • PIAs
  • Visual Studio IDE tools
  • F1 Help from the Visual Studio code editor

Setting Esri assemblies Specific Version property

To have a successful compile of a migrated ArcGIS 10 Visual Studio development project, confirm that all Esri assemblies have the Specific Version property set to false. To do this, follow these steps for each Esri assembly your project references:
  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:
  3. Repeat the steps for all Esri assemblies you have referenced.
The following Visual Studio error is an example of a compiler error that can occur when an ArcObjects development project created in ArcGIS 9.3 with Esri assembly Specific Version property set to true is ported to ArcGIS 10.1:
Error: Cannot unregister assembly "C:\MyGISProjects\MapControlApplication\bin\Debug\MapControlApplication.exe". Could not load file or assembly 'ESRI.ArcGIS.Carto, Version=10.0.0.0, Culture=neutral, PublicKeyToken=8fc3cc631e44ad86' or one of its dependencies. The system cannot find the file specified.

Upgrading enumerations

At ArcGIS 10.1, changes have been made to the esriLicenseProductCode, esriProductCode, and esriLicenseExtensionCode enumerations. The changes have been made to the enumeration description, which requires you to make changes to your code when recompiling for 10.1.

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 product:
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 of ArcGIS for Desktop:
Registry hive
Key value
HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Desktop10.1
InstallDir
  • Version number of the installed ArcGIS for Desktop product:
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.1, 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

License initialization

Starting at 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, which allows for the most flexibility in your application. A developer can also use the ArcGIS License Initializer wizard. For developers using Esri Visual Studio 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

Starting at ArcGIS 10, all stand-alone ArcGIS applications must bind to a runtime. Runtime binding refers to locating the appropriate ArcGIS product installation of a stand-alone ArcGIS for 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.1 runtime.
When the ArcObjects .NET SDK is installed, the ESRI.ArcGIS.Version assembly is installed by default in the C:\Program Files\ArcGIS\DeveloperKit10.1\DotNet folder for you to add as a reference in the Visual Studio IDE.

Migrating an ArcGIS 9.3.x or 10 application to 10.1 using the LicenseControl

To migrate ArcGIS 9.3.x or 10 Desktop and Engine applications that were built using the License Control to 10.1, perform the following steps:
  1. Install the ArcObjects .NET SDK.
  2. Upgrade Visual Studio 2003, 2005, and 2008 projects to Visual Studio 2010.
  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 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 (that is, before any other ArcObjects code is used), the following runtime error message appears:

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

Runtime binding must also be performed on code written using the ESRI.ArcGIS.esriSystem.AoInitialize class. The following are two cases when you will have code using this class:
Code written manually—To migrate manually written code from an ArcGIS 9.3.x or 10 application to 10.1 using the ESRI.ArcGIS.esriSystem.AoInitialize class, perform the following steps:
  1. Install the ArcObjects .NET SDK.
  2. Upgrade Visual Studio 2003, 2005, and 2008 projects to Visual Studio 2010.
  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 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.x or 10 Desktop and Engine applications that were built using the AoInitialize class (and that were constructed using the ArcGIS License Initializer Wizard) to 10.1, perform the following steps:
  1. Install the ArcObjects .NET SDK.
  2. Upgrade Visual Studio 2003, 2005, and 2008 projects to Visual Studio 2010.
  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.x or 10 development project, the ArcGIS License Initializer needs to be run again when migrating to 10.1, since some of the code that the ArcGIS License Initializer generated has changed. See the following screen shot:
  7. The ArcGIS License Initializer overwrites and updates the code that was generated from a previous version.
It is not necessary to add binding code using the ArcGIS License Initializer Visual Studio Add-in to automatically generate licensing code. The initializer adds the binding code automatically and binds to Desktop or Engine. For more control, it is recommended that you write your binding and licensing code.


See Also:

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



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