Upgrade extensions

This topic discusses the extension compatibility with different versions of ArcGIS Enterprise and how to upgrade an older version of SOE or SOI project to be built with a later version of ArcGIS Enterprise SDK.

Extension compatibility

The best practice to deploy extensions to different versions of ArcGIS Enterprise is to compile the extension using the same version of ArcGIS Enterprise SDK as the version of ArcGIS Server where the extension will be deployed. Since how ArcGIS Server works with older versions of extensions is different depending on its version, this section explains the extension compatibility with different versions of ArcGIS Server.

Extension compatibility with ArcGIS Server 11.0

Starting with ArcGIS Server 11.0, deploying SOEs or SOIs built with ArcGIS Enterprise SDK 10.x is no longer supported. In ArcGIS Server 11.0, if you register an SOE or SOI built with the 10.x version of ArcGIS Enterprise SDK, you will see the following error:

This extension cannot be deployed because it is built for ArcGIS Server 10.x and needs to be upgraded to version 11. See 'ArcGIS Enterprise SDK - Upgrade extensions'.

To continue using the older SOE or SOI in ArcGIS Server 11.0, you must upgrade the extension to 11.0, in other words, build the extension with ArcGIS Enterprise SDK 11.0. This process requires development efforts. Follow the instructions in Upgrade steps.

Extension compatibility with ArcGIS Server 10.9.1 or earlier

Deploying an older version of SOE or SOI to ArcGIS Server at 10.9.1 or earlier version is not supported. Even though the extension may still load and function properly in the newer version of ArcGIS Server, the best practice is to recompile the extension using the same version of ArcGIS Enterprise SDK as the version of ArcGIS Server where the extension will be deployed. With that being said, if you want to deploy your SOE or SOI to a specific version of ArcGIS Server, you should compile your SOE or SOI using the same version of ArcGIS Enterprise SDK.

Similarly, if you want to use new features or APIs provided by the newer version of ArcGIS Enterprise SDK, you must upgrade your ArcGIS Server to the same version as the SDK.

Upgrade steps

To upgrade your ArcGIS Enterprise SDK, you should first uninstall any previous version of ArcGIS Enterprise SDK. This can be done through the Control Panel for Windows and the uninstall_EnterpriseSDK command for Linux. Then, you can install the version of ArcGIS Enterprise SDK you need and set up the development environment.

Since ArcGIS Enterprise SDK starts to use the Maven framework to manage SOE and SOI projects at 10.8.1, the upgrade steps are different depending on which version you want to upgrade to.

Upgrade extensions (Maven project)

This scenario applies when you upgrade an existing Java SOE or SOI project built with 10.8.1 or later version of Enterprise SDK. Since your existing SOE or SOI project is already a Maven project, you can modify the project's POM.xml to update the project dependencies, and rebuild the existing project with the later version of Enterprise SDK artifacts.

1. Uninstall the previous version of Enterprise SDK and install the later version of the SDK (see Installation).

   Set up your Java extension development environment properly. Don't forget to reinstall the Maven artifacts.

2. Modify your existing project's POM.xml file to update the SDK artifact and target versions to match the version of the SDK installed.

   The following XML is an example of updating POM.xml to target Enterprise SDK 11.0.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
      <dependency>
         <groupId>com.esri.arcgis.enterprise.sdk</groupId>
         <artifactId>arcgis-enterprise-sdk</artifactId>
         <version>11.0.0</version><!-- For 10.9.1 SDK, this value should be 10.9.1 -->
         <scope>provided</scope>
      </dependency>
   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
    	<plugin>
    		<groupId>com.esri.arcgis.enterprise.sdk</groupId>
    		<artifactId>sdk-plugin</artifactId>
    		<version>11.0.0</version><!-- For 10.9.1 SDK, this value should be 10.9.1 -->
            <dependencies>
                <!-- Include any additional plugin dependencies here if needed -->
            </dependencies>
    		<configuration>
    			<configProp>
    				<Version>1.0</Version>
    				<Author>AuthorName</Author>
    				<Company>CompanyName</Company>
    				<TARGETS>11.0</TARGETS> <!-- Required. For 10.9.1 SDK, this value should be 10.9 -->
    			</configProp>
    		</configuration>
    		...
    	</plugin>

3. Fix the compile errors in your code.

   If you don't see any compile errors, skip this step.

   If your SOE or SOI code that used to work with previous versions of Enterprise SDK fails to with the 11.0 version of the SDK, see API changes in 11.0 and New in 11.0 API to fix the compile errors.

4. Run mvn clean install.

   Now, your project should be successfully built with the later version of Enterprise SDK.

Migrate extensions (from Java project to Maven project)

This scenario applies when you upgrade a Java SOE or SOI project built with 10.8 or previous versions of Enterprise SDK to 10.8.1 or later version of the SDK. Since the Maven framework is used in 10.8.1 or later versions of the SDK, you need to migrate your Java project to a Maven project.

1. Install the later version of Enterprise SDK and set up the development environment (see Installation).

2. Create a new SOE or SOI Maven project using the Maven archetype (see Project creation).

   Since the 10.8.1 Enterprise SDK manages Java SOE or SOI projects using the Maven framework, you should migrate your previous Java SOE or SOI project to a Maven project.

   If your previous SOE or SOI project references any third-party JARs, you must install those JARs to your Maven local repository and reference them at the project's POM.xml file (see Dependency management).

3. Copy the code and other relevant files, such as custom property page files, if any, to the new Maven project.

4. Now you can use mvn install to build your project with the later version of the SDK.