Skip To Content

Introduction to extending services

You can extend ArcGIS Server map and image services (including map and image service extensions, such as feature services) with custom logic that can be executed in ArcGIS clients. There are two ways to extend these service types:

  • Server object extensions (SOE) allow you to create service operations to extend the base functionality of map or image services. SOEs are appropriate if you have some well-defined business logic to perform that is not easily accomplished using the ArcGIS client APIs. Most SOEs do this by using custom code to work with geospatial data and maps.
  • Server object interceptors (SOI) allow you to intercept requests for existing built-in operations of map or image services. This allows you to execute custom logic and alter the behavior of these services by overriding existing operations in a way that is seamless to existing clients. These clients may be applications built with ArcGIS API for JavaScript, ArcGIS Runtime SDK, and more.

What you need to know to develop an extension

Extension development requires knowledge of ArcGIS development tools using Java or the .NET programming languages. It also requires an understanding of REST or SOAP principles. Extensions developed with Java can be deployed to ArcGIS Server on Windows and Linux. Extensions developed with .NET can only be deployed to ArcGIS Server on Windows.

An extension can only be developed for a specific service type, either a map service or an image service. For example, you cannot develop a generic extension that works with both a map service and an image service. In this case, you must develop individual extensions for each service type, one for a map service and the other for an image service.

SOEs and SOIs can be developed using ArcGIS Enterprise SDK. It offers tools, documentation, and samples for both .NET and Java.

  • You can use the ArcGIS Enterprise SDK to develop SOEs to extend map services and develop SOIs to customize the capabilities of map and image services (including feature services and OGC-compliant services). When using this SDK, if you want to write custom ArcGIS Server Manager property pages for your extensions beyond those that are automatically generated, you must have knowledge of Web Forms development using HTML and JavaScript.

Server object extensions

SOEs are appropriate if you want to create service operations to extend the base functionality of map and image services (including map and image service extensions, such as feature services). They provide the following advantages:

  • You can expose an SOE as a REST or SOAP web service, allowing custom clients built on top of the ArcGIS client APIs and any other REST or SOAP client to easily invoke them. In fact, your REST SOEs will be shown in the ArcGIS Services Directory and can expose the typical object types that the ArcGIS client APIs understand, mostly in JSON format.
  • When you build an SOE, you're providing coarse-grained methods that perform work on ArcGIS Server, rather than making a large number of calls from the client to the server. SOEs encapsulate business logic very efficiently, providing an ideal environment to execute your calls quickly.

You might develop an SOE if you want to expose functionality that is not available in any other manner or that needs to be executed very quickly. SOEs are for experienced developers and require knowledge of various development platforms.

Do you need an SOE?

SOEs require knowledge of web development, ArcGIS development tools, and programming languages such as Java or a .NET-based language such as C#. They must also go through a deployment process to be made available to your server. Before you develop a server object extension, you might consider some easier alternatives.

The simplest alternative to developing an SOE may be to create a geoprocessing model that accomplishes your business logic, and then publish it as a service. You can use ModelBuilder to interactively drag, drop, and connect the needed tools instead of writing custom business logic code. Geoprocessing services also allow asynchronous execution, allowing you to start a job, do something else, and come back later to check the results.

One drawback of geoprocessing services is that they have a relatively large memory footprint and may run slower than SOEs. If you're running a process only a few times a day, this might not be an issue. However, if you are running a process many times a day, or with many concurrent users, it might be worth investing the time to build an SOE.

Many developers have written custom code in the past for various tasks that are now attainable without it. For a detailed discussion of ways to approach web mapping challenges without needing to develop extensions, see Alternatives to server object extensions.

Server object interceptors

SOIs are appropriate if you want to change the behavior of existing map or image service operations (including map and image service extensions, such as feature service operations). For example, you can change the behavior of a query or map image export request.

You might also develop SOIs to implement custom business logic, such as security or auditing requirements that are not met by the default map or image service, for example:

  • Auditing and logging all requests—For debugging purposes, you can create a series of SOIs that log detailed information about incoming requests, such as full information about the input parameters and the user credentials passed in with the request.
  • Include a watermark on all map images created by the server—A series of SOIs can be created to superimpose a custom watermark on map images created by the server. This allows organizations or hosting companies to ensure proper branding on all images.
  • Postprocessing responses—Additional information from separate business systems not supported by ArcGIS Server could be added to outgoing responses to join spatial data with other types of business intelligence data.
  • Operation-level access control for map services—ArcGIS Server only supports enabling service operations for all users of the service or disabling access completely. A series of SOIs can filter incoming requests based on the user's role to implement operation-level access to the service.
  • Layer-level access control for map services—ArcGIS Server only supports service-level data access; either a user has full access to all service data or the user has no access. A series of SOIs can be implemented to filter access to specific layers or even filter data within a layer based on the user's role.

If you want to accomplish one or more tasks using a series of extensions, you can do so using SOIs. Multiple SOIs can be chained together on one or more services. At any time, you can modify the list of SOIs and the order in which they are executed in the chain.

Do you need an SOI?

SOIs require knowledge of web development, ArcGIS developer tools, and programming languages such as Java or a .NET-based language such as C#. They must also go through a deployment process to be made available to your server. Before you develop an SOI, consider whether this is the functionality you need.

If you are looking to extend your server with new capabilities, consider an SOE or geoprocessing models and scripts. SOIs are suitable for adding new business logic or behavior on top of the existing ArcGIS Server operations in a way that is transparent to existing client applications.