Technical Documents  

Migrating .NET code from ArcGIS 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. These changes may require you to make changes in turn to your existing ArcObjects developments, regardless of the development language you are using.

You can find out information about the reasons for these changes and also the details of the changes in the topic Migrating from 8.3 to 9.0.

In addition, you may encounter issues which are particularly relevant to the .NET environment.

  1. Non-Ole Automation Compliant Types
  2. Changes to members on class interfaces
  3. Changes to Utility and base classes
  4. Capitalization changes

  1. Non-Ole Automation Compliant Types

    The interfaces in ArcObjects contain a few members which are not OLE-compliant, for example the C-style array parameters used in many Geometry members. As COM Interop relies on data types being OLE-compliant, these members are unfortunately not useable in .NET.

    At ArcGIS 8.3, ESRI manipulated the Intermediate Language (IL) of the interop assemblies in order to perform data type conversion and allow the members to be used in .NET successfully. However, at 9.0, with the introduction of other supported environments such as Java, a more reliable and pervasive solution was required to allow access to non-OLE-compliant members.

    In most cases, supplemental interfaces have been added which have members rewritten to use OLE-compliant data types. For example, for members which used C-style arrays, alternative members have been added which use the OLE Automation SAFEARRAY data type to handle the arrays. If you have used these members in your .NET code with ArcGIS 8.3, you should change your code to use the new OLE Automation compatible interfaces when working against ArcGIS 9.0. This subject is discussed, with an example of IEnvelope::DefineFromPoints, in the Interoperating with COM topic in the .NET Programming Techniques section of the Developer Help.

    These supplemental interfaces use the naming convention I<interfacename>GEN. One exception to this naming convention is the IGeometryBridge interface. In order to avoid the 'bloating' of geometry classes with many new interfaces, OLE-compliant versions of many geometry members can be found grouped together on the IGeometryBridge interface of the GeometryEnvironment class.

    The table below gives a listing of the OLE-compliant interfaces and members, and their compliant equivalents.


    Interface Non-compliant Member Interface of equivalent compliant member 9.0 ESRI.ArcGIS namespace
    IAffineTransformation2D DefineFromControlPoints IAffineTransformation2D3GEN Geometry
    IAffineTransformation2D3 DefineConformalFromControlPoints IAffineTransformation2D3GEN Geometry
    IAffineTransformation2D3 QueryLinearCoefficients IAffineTransformation2D3GEN Geometry
    IAffineTransformation2D3 SetLinearCoefficients IAffineTransformation2D3GEN Geometry
    IBezierCurve QueryCoords IBezierCurveGEN Geometry
    IBezierCurve PutCoords IBezierCurveGEN Geometry
    IClassify ClassBreaks IClassifyGEN::Classify esriSystem
    IClassify SetHistogramData IClassifyGEN::Classify esriSystem
    IEnvelope DefineFromPoints IEnvelopeGEN Geometry
    IEnvelope DefineFromWKSPoints IEnvelopeGEN Geometry
    IForwardStar QueryAdjacentEdges IForwardStarGEN Geodatabase
    IForwardStar QueryAdjacentJunctions IForwardStarGEN Geodatabase
    IGeometryCollection AddGeometries IGeometryBridge Geometry
    IGeometryCollection InsertGeometries IGeometryBridge Geometry
    IGeometryCollection QueryGeometries IGeometryBridge Geometry
    IGeometryCollection SetGeometries IGeometryBridge Geometry
    IMultiPatch QueryBeginningRings IGeometryBridge Geometry
    IMultiPatch QueryFollowingRings IGeometryBridge Geometry
    INetElementBarriers SetBarriers INetElementBarriersGEN NetworkAnalysis
    INetElementBarriers2 SetBarriersByEID INetElementBarriersGEN NetworkAnalysis
    INetSolverWeights SetFilterRanges INetSolverWeightsGEN NetworkAnalysis
    IPiecewiseTransformation DefineFromControlPoints IPiecewiseTransformationGEN EditorExt
    IPointCollection AddPoints IGeometryBridge Geometry
    IPointCollection InsertPoints IGeometryBridge Geometry
    IPointCollection QueryPoints IGeometryBridge Geometry
    IPointCollection ReplacePoints IGeometryBridge Geometry
    IPointCollection SetPoints IGeometryBridge Geometry
    IPointCollection2 GetPoints IGeometryBridge Geometry
    IPointCollection4 AddWKSPointZs IGeometryBridge Geometry
    IPointCollection4 QueryWKSPointZs IGeometryBridge Geometry
    IPointCollection4 SetWKSPointZs IGeometryBridge Geometry
    IProjectedCoordinateSystem Forward IProjectedCoordinateSystem4GEN Geometry
    IProjectedCoordinateSystem GetParameters IProjectedCoordinateSystem4GEN Geometry
    IProjectedCoordinateSystem Inverse IProjectedCoordinateSystem4GEN Geometry
    IProjectedCoordinateSystem2 InverseWithShift IProjectedCoordinateSystem4GEN Geometry
    IProjection GetDEfaultParameters IProjectionGEN Geometry
    IProjectiveTransformation2D DefineFromControlPoints IProjectiveTransformation2DGEN Geometry
    IProjectiveTransformation2D SetTransformationParameters IProjectiveTransformation2DGEN Geometry
    IProjectiveTransformation2D QueryTransformationParameters IProjectiveTransformation2DGEN Geometry
    ISegment Densify IGeometryBridge Geometry
    ISegmentCollection AddSegments IGeometryBridge Geometry
    ISegmentCollection InsertSegments IGeometryBridge Geometry
    ISegmentCollection QuerySegments IGeometryBridge Geometry
    ISegmentCollection ReplaceSegments IGeometryBridge Geometry
    ISegmentCollection SetSegments IGeometryBridge Geometry
    ISpatialReference2 ApplyPrecision ISpatialReference2GEN Geometry
    ISpatialReference2 ApplyXYPrecision ISpatialReference2GEN Geometry
    ITopologicalOperator2 ConstructBuffers IGeometryBridge Geometry
    ITraceFlowSolver FindPath ITraceFlowSolverGEN NetworkAnalysis
    ITraceFlowSolver PutEdgeOrigins ITraceFlowSolverGEN NetworkAnalysis
    ITraceFlowSolver PutJunctionOrigins ITraceFlowSolverGEN NetworkAnalysis
    ITraceFlowSolver2 FindSource ITraceFlowSolverGEN NetworkAnalysis
    ITransformation TransformMeasuresFF ITransformationGEN Geometry
    ITransformation TransformMeasuresFI ITransformationGEN Geometry
    ITransformation TransformMeasuresIF ITransformationGEN Geometry
    ITransformation TransformMeasuresII ITransformationGEN Geometry
    ITransformation TransformPointsFF ITransformationGEN Geometry
    ITransformation TransformPointsFI ITransformationGEN Geometry
    ITransformation TransformPointsIF ITransformationGEN Geometry
    ITransformation TransformPointsII ITransformationGEN Geometry
    ITransformation3D Transform ITransformation3DGEN Geometry
    ITransformationMethod DefineFromControlPoints ITransformationMethodGEN EditorExt
    IUtilityNetwork EstablishFlowDirection IUtilityNetworkGEN Geodatabase
    IUtilityNetwork2 PartialEstablishFlowDirection IUtilityNetworkGEN Geodatabase

    Note The IActiveViewGEN interface provides generic versions of the ExportFrame and Output members; these members are essential for use from the Java API, but you will find the original IActiveView members are useable from .NET.

    The WKSPointsMap2PixelTransform member of IRasterGeometryProc2 is not suitable for use from .NET; however, this method is superseded by IRasterGeometryProc3::PointsMap2PixelTransform.

    The QueryExteriorRings and QueryInteriorRings members of IPolygon, and also the GetConnectedComponents, GetOutermostComponents, QueryExteriorRingsEx, and QueryInteriorRingsEx members of IPolygon2 have no SAFEARRAY alternative in ArcGIS 9.0; future releases may include generic versions of these members.

  2. Changes to Members on Class Interfaces

    This issue affects C# code which declares variables as a Class Interface rather than a class or interface type, for example Envelope versus EnvelopeClass or IEnvelope. At ArcGIS 9.0, the inherited types of the class interface may have changed. The details of why this change occurred are described below the table.

    The list below details which class interfaces are affected by this issue. When recompiling code using these class interfaces you may need to make changes to your code.


    Class interface 9.0 ESRI.ArcGIS Namespace
    AbridgedMolodenskyTransformation Geometry
    AffineTransformation2D Geometry
    AffineTransformation3D Geometry
    BezierCurve Geometry
    CompositeGeoTransformation Geometry
    CoordinateTransformation SurveyExt
    CoordinateFrameTransformation Geometry
    DefinedInterval esriSystem
    DisplayTransformation Display
    Envelope Geometry
    EqualInterval esriSystem
    ForwardStar Geodatabase
    GeoCentricTranslation Geometry
    GeographicCoordinateSystem Geometry
    HARNTransformation Geometry
    HelmertTransformation2D SurveyExt
    LongitudeRotationTransformation Geometry
    MolodenskyBadekasTransformation Geometry
    MolodenskyTransformation Geometry
    NADCONTransformation Geometry
    NaturalBreaks esriSystem
    NetElementBarriers NetworkAnalysis
    NTv2Transformation Geometry
    PiecewiseTransformation EditorExt
    PiecewiseTransformationMethod EditorExt
    PositionVectorTransformation Geometry
    ProjectedCoordinateSystem Geometry
    Projection Geometry
    ProjectiveTransformation2D Geometry
    Quantile esriSystem
    SimpleTransformation2D SurveyExt
    StandardDeviation esriSystem
    TraceFlowSolver NetworkAnalysis
    UnknownCoordinateSystem Geometry
    UtilityNetwork Geodatabase

    As explained in the Class Interfaces topic, the default interface of a COM class is automatically added to each RCW class interface. However, ArcGIS classes generally have the IUnknown interface as the default interface, and this interface is not exposed via COM interop. If the default interface is IUnknown or IDispatch, the next listed interface on the COM class is implemented by the class interface instead. For example, at ArcGIS 8.3 you could use code like that below to instantiate a new EnvelopeClass using IEnvelope, as IEnvelope is the first listed interface (after the default, IUnknown) on the Envelope COM class, and is therefore implemented by the class interface Envelope.

    IEnvelope env = new Envelope();

    However at ArcGIS 9.0, in order to allow the Java API to function correctly, some COM classes had interfaces added to the top of the interface list. For example, the Envelope COM class gained as itís first listed interface (after the default IUnknown), IEnvelopeGEN. This means that at ArcGIS 9.0, the Envelope class interface implements IEnvelopeGEN rather than IEnvelope, and the above code will no longer be legal. However, it can be replaced with either of the alternatives below:

    IEnvelope env = new EnvelopeClass();
    IEnvelope env = new Envelope() as IEnvelope;

    (To complicate matters, the equivalent VB.NET code would not cause a compile error. This is because the VB.NET compiler interprets the code as a command to QI at runtime for the IEnvelope interface, which of course is a successful call as the EnvelopeClass does implement IEnvelope. C# does not allow these 'implicit casts').

  3. Changes to Utility Classes

    The ESRI.ArcGIS.Utility.CATIDs namespace provides classes representing each of the ArcGIS component categories. Each class knows its CATID and exposes static methods (Register and Unregister) which allow you to add and remove a class from the component category.

    At ArcGIS 8.3, the CATIDs namespace and contents were provided as a developer sample. At ArcGIS 9.0, this was converted to a core assembly, present in the \DotNet subfolder of your ArcGIS installation along with the interop assemblies. In addition to this, some classes were renamed for consistency with the underlying CATID name. For example, at 8.3, you may have used the MxCommand class; at 9.0 this class is called MxCommands. In addition to these changes, new classes were added to represent the new 9.0 categories.

    The Migrating from 8.3 to 9.0 topic lists all the classes affected.

  4. Capitalization Changes

    Certain structure definitions are originally defined outside of the ESRI libraries; for example, the tagRECT structure is originally defined in the Windows API. The change in the structure of ESRI's libraries between 8.3 and 9.0, the original location of such definitions, and the fact that the MIDL compiler used to compile the libraries is case-insensitive, has resulted in certain structures changing capitalization.

    As C# is a case-sensitive language, any changes in the capitalization if class, interface, member, parameter or structure names will need to be reflected in C# source code. Visual Basic .NET is not case-sensitive, and will automatically correct any such case changes.

    The table below gives details of such changes.


    8.3 Name 9.0 Name 9.0 ESRI.ArcGIS Namespace
    tagPOINT.X tagPOINT.x Display
    tagPOINT.Y tagPOINT.y Display
    tagPROPPAGEINFO.Size tagPROPPAGEINFO.size Framework
    tagRECT.Left tagRECT.left Display
    tagRECT.Right tagRECT.right Display
    tagRECT.Top Display
    tagSTATSTG.Type tagSTATSTG.type esriSystem
    tagSTATSTG.CLSID tagSTATSTG.clsid esriSystem