Technical Documents  

Migrating from 8.3 to 9.0

ArcGIS 9.0 introduces a change in the structure of the type libraries that define the ArcObjects classes and interfaces that you use as a developer. The new type libraries may require some changes to your existing ArcObjects developments. This document describes the reasons for these changes, the steps that can be taken to move existing ArcObjects code from 8.x to 9.0, and some utilities to help you in this task.

Background

At ArcGIS 8.x, all of the type library information was held in one single file (with the exception of the extensions and controls). This meant that to access ArcObjects inside of a Visual Basic project you simply had to add a reference to the ESRI Object Library (esricore.olb). In code you could then declare types defined within esricore.olb file using syntax such as:

Dim pAV as esriCore.IActiveView

In the preceding example the library name, esriCore, has been explicitly given. This is not absolutely necessary and the following could also be used with the same effect:

Dim pAV as IActiveView

The advantage of the former version is that there is no ambiguity as to which interface is being used. There could be other (Microsoft or 3rd party) referenced type libraries that define an interface with the same name, and, depending on the relative priority of the libraries, Visual Basic could use an interface that was not intended. Therefore it is generally recommended when making declarations that the type library name is used as a prefix. This also applies to the instantiation of new objects and the implementation of interfaces:

Set pEnv = new esriCore.Envelope
Implements esriCore.ITool

At ArcGIS 9.0 there has been a change to a more modular arrangement of ArcObjects, meaning that there are many different type libraries to contain all of the ArcObjects type information - effectively esriCore.olb has been split up into smaller, more manageable and modular libraries. The libraries are grouped mainly according to functionality, for example: Geometry, Cartography, Geodatabase etc.

What changes are required for 9.0?

The reorganisation of the ArcGIS type libraries has two main impacts on you as a developer:

  1. Instead of simply adding a reference to the single ESRI Object Library to your project, you will be required to add references to all those libraries that you wish to make use of (or simply all of them if you wish). If you develop with VBA this requirement should have little impact on you, since all the common ArcGIS library references are automatically added to the VBA environment of each ArcGIS application.
  2. In existing source code, any explicit use of the type library name such as esriCore will have to be changed to use the appropriate new library name. This includes the following cases:
    • Declarations (including parameters in procedures) 
      Dim pEnv As esriCore.IEnvelope --> Dim pEnv As esriGeometry.IEnvelope
      Dim pFillSym As esriCore.IFillSymbol --> Dim pFillSym As esriDisplay.IFillSymbol
      ZoomToPoint(inPt As esriCore.IPoint) --> ZoomToPt(inPt As esriGeometry.IPoint)
    • Instantiations 
      Set pPt = New esriCore.Point --> Set pPt = New esriGeometry.Point
    • Implementations 
      Implements esriCore.ITool --> Implements esriSystemUI.ITool
    • ProgIDs (the text alias for a CLSID) 
      Dim pUID as New UID
      pUID.Value = "esriCore.ZoomInTool" --> pUID.Value = "esriArcMapUI.ZoomInTool"

      However if CLSIDs are used then this is not an issue (the CLSIDs have not changed for ArcObjects) and no code changes are required. For example the following will continue to work between 8.x and 9.0:

      Dim pUID as New UID
      pUID.Value = "{E1F29C6B-4E6B-11D2-AE2C-080009EC732A}"
  3. The ESRILicenseInfo coclass used in ArcGIS 8.x to manage licensing has been deprecated. When migrating to the new 9.x platform, revise your license code to use the AoInitialize coclass instead of ESRILicenseInfo.

    Detailed information on AoInitialize and its interface, IAoInitialize, is available in its reference documentation. A VB code example of the updated initialization process is available. In addition, a LicenseInitializer add-in is provided for both VB6 and Visual Studio.Net. If you are migrating code to the new Java and C++ APIs for ArcGIS Engine, a sample illustrating the license initialization process is also available.

  4. In addition, there are some issues which are particularly relevant to the .NET environment including:
    • Non-Ole Automation Compliant Types
    • Changes to members on class interfaces
    • Changes to Utility and base classes
    • Capitalization changes

    To see details on these .NET specific issues click here.

There are other minor changes to ArcObjects that might require changes to your source code. To see details click here.

When should the code changes be made?

Many deployed ArcGIS customizations will continue to work against 9.0, since the GUIDs for the ArcObjects classes and interfaces were not changed between ArcGIS 8.3 and 9.0. However it is recommended that all source code is recompiled and redeployed for 9.0, since there are some scenarios which will cause existing deployments to fail:

  1. Any software that uses the ProgID strings (as in the ProgID example above) for ArcGIS objects will have to be changed to use the new ArcGIS library names. Thus if such code exists in a compiled component then it will have to be altered and redeployed to work with ArcGIS 9.0.
  2. Some infrequently used classes and interfaces that existed at ArcGIS 8.3 were removed from 9.0. Full details are recorded in the document Type Changes between ArcGIS 8.3 and ArcGIS 9.0.
  3. VBA deployments will fail if they contain any occurrences of esriCore in the code.
  4. Non-modal dialogs implemented in Visual Basic will not work by default with ArcGIS 9.0 applications. This problem can be solved in a number of ways; see Using modeless Visual Basic dialogs in ArcGIS.

What helper utilities exist?

Various tools are available to help you migrate your source code to work with ArcGIS 9.0. These tools were used internally by ESRI to update the ArcGIS Developer Samples for 9.0.

The Visual Basic 6 Code Converter add-in will automatically do the following to the currently loaded VB project and all contained code modules:

  1. Remove the ESRI Object Library entry from the project's references
  2. Replace all occurrences of esriCore in the source code with the appropriate library name. For example 'Set pPoly = New esriCore.Polygon' will be replaced by 'Set pPoly = New esriGeometry.Polygon'
  3. Add all of the required new references to the project according to object types found in the code, even if they are not prefixed by the library name. For example if 'Dim pPoly As IPolygon' is found then a reference to esriGeometry is added.
  4. Compile the project.

The VB6 Code Converter add-in can also be run in batch mode; allowing many VB projects to be converted in one process. In the case where it finds any problems with the automatic conversion, these problems are logged and reported upon completion allowing manual inspection and correction.

The .NET Code Converter Add-in for C# or Visual Basic .NET solutions, operates in a similar manner to the Visual Basic 6 add-in.

The Library Locator is a utility for finding the type library that contains a specified interface, coclass, enumeration, or structure. You can also get this information from the ArcGIS Developer Help.

The Visual Basic 6 Automatic References add-in is useful for quickly adding type library references to a project.

Other changes required at 9.0

The following sections detail fairly minor changes required to existing developments in order to work with 9.0. These details are not relevant for most projects.

Visual Basic modeless forms

As previuosly mentioned, non-modal dialogs implemented in Visual Basic will not work by default with ArcGIS 9.0 applications. This problem can be solved in a number of ways; see Using modeless Visual Basic dialogs in ArcGIS.

Controls QueryInterface changes

At 8.3, the ArcGIS controls MapControl and PageLayoutControl, each had just one interface, which was the default interface for the object. At ArcGIS 9.0 new interfaces were added to the controls (for example IMapControl3), and a new default interface created which amalgamates the other interfaces. In some development environments, in particular Visual Basic 6 and .NET, this means that the behavior of QueryInterface (QI) calls will differ at 9.0 from the behavior at 8.3, and may require changes to your source code.

Visual Basic 6 contains the real control inside a wrapper object known as an extender object. This extender object creates the default interface 'on the fly', but does not implement the interfaces on the true control object. So the following code, which returned true at 8.3, will return false at 9.0.

TypeOf PageLayoutControl1 Is IPageLayoutControl

It should be recoded as follows:

TypeOf PageLayoutControl1.Object Is IPageLayoutControl

Similarly the following code will fail at 9.0

Dim pPageLayoutControl As IPageLayoutControl
Set pPageLayoutControl = PageLayoutControl1

It should be recoded as follows:

Dim pPageLayoutControl As IPageLayoutControl
Set pPageLayoutControl = PageLayoutControl1.Object

The VB6 Code Converter add-in will log warnings when it finds usage of controls interfaces in source code.

Enumerations starting 'tagesri'

At ArcGIS 8.3, it was possible (though uncommon) to use an alternative name for some enumerations, starting with 'tag'. These alternative names are unavailable with 9.0 For example, this code will no longer compile:

Dim eGeomType As tagesriGeometryType
eGeomType = pGeometry.GeometryType

To correct the code, use esriGeometryType instead of tagesriGeometryType. The Visual Basic 6 Code Converter add-in will automatically make this change for you. Note that structures (as opposed to enumerations) with names starting 'tag', for example tagRECT, are unchanged at 9.0.

Changes to esriSR* enumerations

Some of the values have changed in enumerations with names starting 'esriSR'. For example, in the esriSRGeoTransformationType enumeration, at ArcGIS 8.3 the value for esriSRGeoTransformation_NAD1927_To_WGS1984_1 was 8070, at ArcGIS 9.0 it is 1170. The changes have been made to bring the values in line with the EPSG database (http://www.epsg.org).

These changes do not require any changes to your source code. Even if you used the old numbers directly in your code (rather than the enumeration identifers), your programs should still continue to work, since the old values are internally remapped to the new values by ArcMap. It is still recommended however that you use the enumeration identifiers in your source code rather than the numeric values.

Plug-in data source changes

The IPlugInFastRowCount interface has been deprecated. Code using this interface will continue to work, but you are recommended to instead implement the new interface IPlugInRowCount.

There are some new plug-in data source interfaces that provide additional functionality. Support for addition and removal of indexes is provided by IPlugInIndexInfo, IPlugInIndexManager and IPlugInWorkspaceHelper2. Copy, rename and delete operations are supported by IPlugInFileOperations and IPlugInFileOperationsClass. Other new interfaces are IWorkspaceFactoryFileExtensions and IPlugInCreateWorkspace. See Extending ArcObjects for more details.

If your plug-in data source is implemented in Visual C++, you may have to make the following changes when migrating from 8.3 to 9.0.

  1. If you implement IPlugInMetadataPath, there has been a minor case change. Alter occurrences of get_metadataPath to get_MetadataPath.
  2. If you implement IPlugInFastQueryValues, the signature of the FastQueryValues method has changed.

    At 8.3 - IPlugInFastQueryValues::FastQueryValues(long* values)

    At 9.0 - IPlugInFastQueryValues::FastQueryValues(FieldValue* values)

    For example your code may change as follows (old code in comments):

    [CursorHelper.h]
//STDMETHOD(FastQueryValues)(long * Values); //8.3
//struct FieldValue
//{
// VARIANT     m_value;
// ULONG       m_length;
// DWORD       m_status;
//};

STDMETHOD(FastQueryValues)(FieldValue * Values); //9.0

[CursorHelper.cpp]
//STDMETHODIMP CWPTCursorHelper::FastQueryValues(long * pValues)  //8.3
STDMETHODIMP CWPTCursorHelper::FastQueryValues(FieldValue * pValues)  //9.0
{
 //FieldValue* Values = reinterpret_cast(pValues);
 FieldValue* Values = pValues;
 ...
}

IEditCache

At ArcGIS 9.0 the edit cache has been renamed to map cache and moved into the core ArcMap user interface because it now operates either inside or outside an edit session. For more details on this change see What's new in ArcMap: Editing in the ArcGIS Desktop Help.

If you used the IEditCache interface at ArcGIS 8.3, you will need to change your code to use IMapCache instead. The following example shows VBA code that toggles the auto-cache state, with the old 8.3 code commented out.

Public Sub ToggleAutoCache()

  Dim pMxDoc As IMxDocument
  Set pMxDoc = ThisDocument
  Dim pCache As IMapCache
  Set pCache = pMxDoc.FocusMap

  '8.3 code commented out
  'Dim pUID As IUID
  'Set pUID = New esricore.UID
  'pUID.Value = "esriCore.AutoCache"
  'Dim pCache As IEditCache
  'Set pCache = Application.FindExtensionByCLSID(pUID)

  If pCache.AutoCacheActive Then
    pCache.AutoCacheActive = False
  Else
    pCache.AutoCacheActive = True
  End If
End Sub