ArcGIS Enterprise

Migrating ArcObjects SOEs and SOIs to ArcGIS Enterprise SDK

In case you missed the news, ArcGIS Enterprise 10.9.x, part of the ArcGIS 2021 product releases, will be the last release series that supports publishing and consuming of services from ArcMap. This means it is time to start migrating any services using the ArcMap service runtime to the ArcGIS Pro service runtime. ArcGIS Enterprise 10.9 introduced tooling to assist you in migrating your compatible services’ runtimes, but services with server object extensions (SOEs) or server object interceptors (SOIs) cannot be migrated with these 10.9 migration tools. This blog will focus on the workflows for migrating ArcMap based services with ArcObjects SOEs and SOIs to ArcGIS Pro based services with SOEs and SOIs built with ArcGIS Enterprise SDK.

What are the ArcMap service runtime and ArcGIS Pro service runtime in ArcGIS Enterprise?

ArcGIS Server currently includes two internal service runtimes that power nonhosted services: the ArcMap service runtime and the ArcGIS Pro service runtime.

If a service is published from ArcMap, ArcMap generated service definition files, or ArcMap based applications, such as the ArcMap ArcPy Publishing toolset, ArcObjects, or ArcGIS Engine applications, the service will be automatically powered by the ArcMap service runtime in ArcGIS Server and can be called an ArcMap based service. If a service is published from ArcGIS Pro, ArcGIS Pro generated service definition files, or ArcGIS Pro based applications, such as the ArcGIS Pro ArcPy Sharing module, the service will be automatically powered by the ArcGIS Pro service runtime in ArcGIS Server and called an ArcGIS Pro based service.

The service runtime used for each service is shown in Manager as seen in the following example (for ArcGIS Server 10.9):

ServermanagerServiceRuntime

Similarly, SOEs and SOIs can be built with different SDKs to work with these two service runtimes. ArcObjects SDK can be used to develop SOEs and SOIs for services using the ArcMap service runtime. ArcGIS Enterprise SDK, introduced in the 10.6.1 release, allows developing SOEs and SOIs for services using the ArcGIS Pro service runtime. Once an SOE or SOI is uploaded to ArcGIS Server, you can find the service runtime that the SOE or SOI is able to work with from the Provider column, as shown below:

servermanagerExtentionPage

The service runtime that an SOE or SOI supports depends on which SDK it is built with. SOEs and SOIs built with ArcObjects SDK can be enabled with services using the ArcMap service runtime but not the ArcGIS Pro service runtime. Likewise, SOEs and SOIs built with ArcGIS Enterprise SDK can be applied to ArcGIS Pro based services but not ArcMap based services.

Removal of the ArcMap service runtime from ArcGIS Enterprise

The ArcGIS Enterprise 10.9.1 release, part of the ArcGIS 2021 product releases, will be the last one that includes the ArcMap service runtime. Starting with the ArcGIS 2022 product releases, the ArcMap service runtime will be removed from the software, and it will no longer be possible to publish or consume ArcMap based services. See Removal of ArcMap-based runtime from ArcGIS Enterprise for more details.

How will SOEs and SOIs be affected?

ArcObjects SOEs and SOIs continue to be supported in the 10.9.x series of ArcGIS Enterprise. The 10.9.x ArcObjects SDK is still provided to build 10.9.x SOEs and SOIs. Even though there is no plan to release ArcMap 10.9, it is still supported to publish services from 10.8.1 or previous versions of ArcMap to 10.9.x ArcGIS Server sites (both federated and nonfederated) and apply the 10.9.x ArcObjects SOEs and SOIs to these services.

After the 10.9.1 release, since the ArcMap service runtime will be removed from ArcGIS Enterprise, ArcObjects SOEs and SOIs will not be supported. This means that ArcObjects SDK will not be provided as part of the ArcGIS 2022 releases, and it will not be possible to build or consume ArcObjects SOEs or SOIs. However, ArcGIS Enterprise SDK will still be provided as part of the ArcGIS 2022 product releases, and the support of SOEs and SOIs built with ArcGIS Enterprise SDK for ArcGIS Pro based services will not be impacted by the removal of the ArcMap service runtime.

Migration strategies for SOE and SOI users

Because the ArcGIS Server 10.9.x series will be the last set of releases to include the ArcMap service runtime, with migration tooling and user interfaces introduced to help migrate ArcMap based services, it is recommended to start migrating your services, ArcObjects SOEs, and ArcObjects SOIs to ArcGIS Enterprise 10.9.x. This includes the following two steps:

  1. Migrate the ArcMap based map services or image services to use the ArcGIS Pro runtime.
  2. Migrate the ArcObjects SOE or SOI to be built with ArcGIS Enterprise SDK.

The first step typically does not require republishing the service, and can be achieved by updating the existing service’s service runtime via Editing Runtime in Server Manager or the UpdateArcMapServices utility. Note that all the ArcObjects SOEs and SOIs that have been applied to the service must be disabled before the service runtime is updated.

The second step requires development work. If you are not the SOE or SOI developer, you must contact the SOE or SOI developer or vendor to help build the SOE or SOI with ArcGIS Enterprise SDK. If you are the SOE or SOI developer, follow the steps in the next section to plan for migrating the SOE or SOI for ArcGIS Pro based services.

If you have not been able to migrate your services, SOEs, or SOIs to use the ArcGIS Pro service runtime, you should keep ArcGIS Enterprise at a version that contains the ArcMap service runtime until they are ready to fully move to the ArcGIS Pro service runtime. This means remaining on ArcGIS Enterprise 10.9.x or earlier. Note that ArcGIS Enterprise 10.9.1 will follow the long-term support product life cycle, ensuring support into 2027. The same support cycle applies to 10.9.1 ArcObjects SOEs and SOIs.

Migration strategies for SOE and SOI developers

To plan for migrating the existing ArcObjects SOEs and SOIs to be built with ArcGIS Enterprise SDK, it is important to understand the development pattern of ArcGIS Enterprise SDK and how it is different from ArcObjects SDK.

Compared to ArcObjects SDK, Enterprise SDK provides APIs and tools to develop and build SOEs and SOIs in a similar manner, but with more feature improvements. For most SOE and SOI developers, it should be easy to migrate. This section compares APIs and SDK tools of ArcGIS Enterprise SDK with those in ArcObjects SDK and discusses the migration efforts from code change and refactoring, and project build and management perspectives.

 ArcGIS Enterprise SDK APIs

The APIs provided by ArcGIS Enterprise SDK are still COM-based and have the same coding pattern as the ArcObjects APIs.

Most of the interfaces and classes in the Geodatabase, Server, and Geometry libraries of ArcGIS Enterprise SDK are the same as those in ArcObjects SDK. If your ArcObjects SOE or SOI uses most of the APIs from these libraries, there should be minimum efforts needed to migrate the code to ArcGIS Enterprise SDK and typically code refactoring is not necessary.

Certain APIs are intentionally removed from ArcGIS Enterprise SDK under the following conditions:

In the Carto library, many inherited interfaces with numbers in their name are removed from ArcGIS Enterprise SDK and their methods are added to the original interface. For example, IMapServer2, IMapServer3, and so on, are no longer in ArcGIS Enterprise SDK, but methods implemented by these interfaces are added to IMapServer in the API. If these interfaces are used in your SOE or SOI, code changes will be needed when you migrate your project.

In the Carto library, the interfaces and classes related to custom layout and print functions are removed from ArcGIS Enterprise SDK. The Geoprocessing library, which is used for business logic with geoprocessing, and the Display library for layer rendering and symbology are also removed. In these cases, better alternatives are available now and can be used. You may need to refactor your SOE or SOI code and adopt alternative approaches suggested in custom layout and print functions, business logic with geoprocessing, and layer rendering and symbology, to integrate into your workflow.

To view the list of all the libraries in ArcGIS Enterprise SDK, refer to the API reference page. You may also refer to Design philosophy for ArcGIS Enterprise SDK for more explanations on the API changes. If you would like to request functions or APIs for SOEs and SOIs that are not available with ArcGIS Enterprise SDK, contact Technical Support.

ArcGIS Enterprise SDK tools

ArcGIS Enterprise SDK provides tools and project templates to help build and manage SOE and SOI projects.

Like ArcObjects SDK, ArcGIS Enterprise SDK provides .NET templates to help create SOE or SOI projects with similar boilerplate code automatically implemented. For Java SOE or SOI development, in ArcGIS Enterprise SDK 10.8 or earlier releases, the ArcGIS Eclipse plug-in and SOEPackager tool are provided for the SOE and SOI project creation and build process, which works in the same way as those in ArcObjects SDK. Starting with ArcGIS Enterprise SDK 10.8.1, Maven integration is introduced, which allows managing Java SOE and SOI projects in the Maven framework.

Once an SOE or SOI project is built with ArcGIS Enterprise SDK, an .soe file will be generated, which can then be uploaded to ArcGIS Server and enabled with a service in a similar manner as an ArcObjects SOE or SOI.

Migration steps

Since new interfaces and classes have been added in each release of ArcGIS Enterprise SDK, consider upgrading to the latest 10.9.x series to work on SOE and SOI migration. Remember that the version of ArcGIS Enterprise SDK used to build the SOE or SOI should be the same as the version of ArcGIS Enterprise that the SOE or SOI will be deployed to.

To start migrating your ArcObjects SOEs and SOIs to be built with ArcGIS Enterprise SDK, you can follow these step-by-step instructions:

With the services that have been migrated to use the ArcGIS Pro service runtime, you can then test the SOE or SOI built with ArcGIS Enterprise SDK.

Note that ArcGIS Enterprise SDK is a separate SDK from ArcObjects SDK, with separate APIs and SDK tools provided to develop SOEs and SOIs for ArcGIS Pro based services. These two SDKs cannot be used together. For example, a .NET SOE or SOI created from the ArcGIS Enterprise SDK project template cannot use libraries from ArcObjects SDK. A Java SOE or SOI project using ArcGIS Enterprise SDK libraries cannot be compiled with tools provided by ArcObjects SDK.

We hope to make the transition from the ArcMap service runtime to the ArcGIS Pro service runtime as smooth as possible for SOE and SOI users and developers. Let us know if you have any questions below and we hope this helps with your ArcGIS Enterprise and ArcGIS Server workflows!

About the author

Hanhan is a Product Engineer for ArcGIS Enterprise SDK. When she is not at work or home, she enjoys embracing the ocean, snowy mountains, deserts, and starry sky of Southern California.

Leave a Reply

Please Login to comment

Next Article

ArcGIS Server Security 2021 Update 2 Patch is now available

Read this article