This topic describes extension compatibility across different versions of ArcGIS Enterprise and explains how to upgrade an existing server object extension (SOE) or server object interceptor (SOI) project using a newer version of ArcGIS Enterprise SDK.
Extension compatibility
When deploying extensions to ArcGIS Enterprise, the recommended practice is to compile the extension using the same version of ArcGIS Enterprise SDK as the target ArcGIS Server version. However, this is not always a strict requirement.
Extension compatibility depends on the versions of ArcGIS Server and ArcGIS Enterprise SDK used. This section describes compatibility across different ArcGIS Server versions.
Extension compatibility with ArcGIS Server 12.2
ArcGIS Server 12.2 supports server object extensions (SOEs) and server object interceptors (SOIs) built with ArcGIS Enterprise SDK 12.2.
The recommended practice is to compile extensions using ArcGIS Enterprise SDK 12.2 before deploying them to ArcGIS Server 12.2.
Extensions built with earlier versions of ArcGIS Enterprise SDK may require compatibility verification before deployment. In particular, compatibility with extensions built using ArcGIS Enterprise SDK 12.0 or 12.1 should be confirmed against the target ArcGIS Server 12.2 environment.
Extensions built with ArcGIS Enterprise SDK 11.x are not supported for deployment to ArcGIS Server 12.2.
Extension compatibility with ArcGIS Server 12.1
Starting with ArcGIS Enterprise SDK 12.1, .NET-based server object extensions (SOEs) and server object interceptors (SOIs) target .NET 10.
SOEs and SOIs built with ArcGIS Enterprise SDK 12.0 targeting .NET 8 are not supported on ArcGIS Server 12.1.
To deploy existing extensions to ArcGIS Server 12.1, you must upgrade and rebuild them using ArcGIS Enterprise SDK 12.1 with .NET 10.
For optimal compatibility, compile extensions using the same version of ArcGIS Enterprise SDK as the target ArcGIS Server version.
Extension compatibility with ArcGIS Server 12.0
Starting with ArcGIS Server 12.0, deploying SOEs or SOIs built with ArcGIS Enterprise SDK 11.x is no longer supported.
If you attempt to register an SOE or SOI built with ArcGIS Enterprise SDK 11.x on ArcGIS Server 12.0, the following error appears:
This extension 'xxxxxx.soe' cannot be deployed because it is built for ArcGIS Server 11.x and needs to be upgraded to version 12. See 'ArcGIS Enterprise SDK - Upgrade extensions'.
When upgrading ArcGIS Enterprise or ArcGIS Server from 11.x to 12.0, all SOEs and SOIs are automatically disabled on map services and image services.
This occurs because ArcGIS Enterprise 12.0 requires extensions to be compiled with ArcGIS Enterprise SDK 12.0. Extensions built with earlier SDK versions, such as 11.x, are not compatible at runtime.
To continue using an SOE or SOI in ArcGIS Server 12.0, you must rebuild the extension using ArcGIS Enterprise SDK 12.0. This process requires additional development work.
Follow the instructions in Upgrade steps.
Extension compatibility with ArcGIS Server 11.5
ArcGIS Server 11.5 supports deploying SOEs and SOIs built with ArcGIS Enterprise SDK 11.x.
Extension compatibility with ArcGIS Server 11.4
ArcGIS Server 11.4 supports deploying SOEs and SOIs built with ArcGIS Enterprise SDK 11.x.
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.
If you attempt to register an SOE or SOI built with ArcGIS Enterprise SDK 10.x on ArcGIS Server 11.0, the following error appears:
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 extension in ArcGIS Server 11.0, you must migrate the project and build it using ArcGIS Enterprise SDK 11.0. This process requires additional development work.
Follow the instructions in Migrate older .NET SOE or SOI projects to 11.
Extension compatibility with ArcGIS Server 10.9.1 or earlier
When deploying SOEs or SOIs to ArcGIS Server 10.9.1 or earlier, the recommended practice is to compile the extensions using the corresponding version of ArcGIS Enterprise SDK.
Although extensions built with older SDK versions may load and function in some newer versions of ArcGIS Server, compatibility is not guaranteed.
To ensure compatibility, compile your SOE or SOI using the SDK version that matches the target ArcGIS Server version.
Similarly, if you want to use new features or APIs introduced in a newer version of ArcGIS Enterprise SDK, you must use a compatible version of ArcGIS Server.
Upgrade steps
To upgrade ArcGIS Enterprise SDK, first uninstall the previously installed version through Windows Control Panel.
Next, configure the development environment and install the required version of ArcGIS Enterprise SDK.
Depending on the SDK version and the existing project configuration, you may need to recompile or migrate your SOE or SOI project.
Upgrade to Enterprise SDK 12.2
Before upgrading to ArcGIS Enterprise SDK 12.2, ensure that the .NET 10 SDK (x64) is installed on your development machine.
To verify the installed .NET SDK version, open a command prompt and run:
dotnet --list-sdksConfirm that .NET SDK version 10.0 is listed. If .NET 10 is not installed, download and install the .NET 10 SDK before proceeding.
After installing ArcGIS Enterprise SDK 12.2, upgrade your existing SOE or SOI project by following these steps:
-
Open Visual Studio, select Open a project or solution, and open your existing SOE or SOI project.
-
In Solution Explorer, expand References.
-
Select the ArcGIS Enterprise SDK libraries (starting with
ESR) and set their Specific Version property toI. Server. Falsein the Properties window. -
Open
Assemblyand updateInfo.cs Targetto match the SDK version.Version For example, when upgrading to ArcGIS Enterprise SDK 12.2, set it to
Target.Version = "12.2" -
Right-click the project in Solution Explorer and select Unload Project. Edit the project's
.csprojfile and updateAddto match the SDK version.In Target Version For example, set it to
<Add.In Target Version >12.2 </ Add In Target Version > -
Right-click the project in Solution Explorer and select Reload Project.
-
Build the project to generate the
.soefile.
Upgrade to ArcGIS Enterprise SDK 12.1
Starting with ArcGIS Enterprise SDK 12.1, .NET 10 is required for developing .NET-based server object extensions (SOEs) and server object interceptors (SOIs).
Before upgrading to ArcGIS Enterprise SDK 12.1, ensure that Microsoft Visual Studio 2026 with the .NET desktop development workload and the .NET 10 SDK (x64) are installed.
To verify the installed .NET SDK version, open a command prompt and run:
dotnet --list-sdksConfirm that a .NET 10 SDK version (10.0.x) is listed. If it is not installed, download and install the .NET 10 SDK before proceeding.
For more information, see Overview of .NET 10 support and System requirements.
Upgrade to Enterprise SDK 11.0
You must follow the instructions in Migrate older .NET SOE or SOI projects to 11. Directly recompiling your older version of SOE or SOI project with Enterprise SDK 11.0 is not supported.
Upgrade to Enterprise SDK 10.9.1 or previous versions
After you install the SDK, you can recompile your older version of the SOE or SOI project by following these steps:
-
Open Visual Studio, click Open a project or solution, and choose your existing SOE or SOI project.
-
Expand References in Solution Explorer on the right side.
-
Select all the ArcGIS Enterprise SDK libraries (starting with "ESRI.Server.") and set their Specific Version property to False in their Properties window.
-
Open
Assemblyand modify the value ofInfo.cs Targetto match your SDK version. For example, if you upgrade to Enterprise SDK 10.9 or Enterprise SDK 10.9.1 , set it toVersion Target.Version = "10.9" -
Double-click your project in Solution Explorer to open and edit the project's .csproj file. Change the
Addto match your SDK version and save this file. For example, if you upgrade to Enterprise SDK 10.9 or Enterprise SDK 10.9.1 , set it toIn Target Version <Add.In Target Version >10.9 </ Add In Target Version > -
Build this project and generate the .soe file.
Sometimes Visual Studio may complain that the .soe file already exists in the
bin\orDebug objfolder and can't be deleted when rebuilding the project. If this happens, you can manually delete these folders and then rebuild the project.