To extend a map or image service (SOE or SOI), you typically write code that implements some required interfaces and performs your business logic. If you're working in Java, you can get started creating an extension using an Eclipse plug-in wizard. If you're working in .NET, you'll start in Visual Studio with a template project. The wizard and templates ensure that your extension implements the required interfaces and can respond to REST or SOAP web service calls using classes in SOESupport.
You can find detailed instructions for coding extension in the documentation for the SDK you are using. It's also possible to create an extension with C++ on Windows, and a sample is included in the ArcObjects SDK for C++.
Appropriate classes and interfaces
The classes and interfaces that are permissible to use when developing SOEs and SOIs depend on the SDK you are using.
ArcObjects SDKs (for .NET and for Java)
Extensions are only supported for map and image services. Because map and image services use a service definition file and do not access a map document (MXD) directly, there are certain classes you should avoid and others you should favor when writing extensions.
Avoid using ArcObjects from the Carto library that are specifically designed for use with MXDs. This includes IMap, ILayer, and items related to data frames and page layouts. Instead, use ArcObjects designed for working with map services, such as MapServer, MapLayerInfos, and MapDescription. Use the interface IMapServerDataAccess to access the datasets underlying each layer in your map.
Libraries not directly related to the map document, such as ESRI.ArcGIS.Geometry and ESRI.ArcGIS.Geodatabase for .NET or com.esri.arcgis.geometry and com.esri.arcgis.geodatabase for Java, are always permissible to use in extensions.
ArcGIS Enterprise SDK
Extensions are only supported for map services.
The ArcGIS Enterprise SDK is bundled with a core set of libraries to facilitate development of custom extensions. The classes and interfaces available in this SDK have all been designed for use in extensions and are permissible to use.
Server object interceptor considerations
When creating server object interceptors (SOIs) you must handle all types of incoming requests even if your SOI is only intended to enhance one or a few of the many operations available with map and image services. This section details the interfaces you need to handle and the approaches available to you depending on if you are implementing security or non-security related functionality.
Intercepting REST, SOAP, and OGC service requests
Map and image services support three different types of requests:
- REST API requests
- SOAP API requests
- OGC requests
In order for an SOI to intercept these requests, you need to implement the following interfaces:
- IRESTRequestHandler—for handling REST API requests
- IRequestHandler2 (for ArcObjects SDKs) or IRequestHandler (for ArcGIS Enterprise SDK)—for handling SOAP API requests including requests made by ArcGIS for Desktop clients (such as ArcMap and ArcGIS Pro)
- IWebRequestHandler—for handling OGC requests
Even if a particular service configuration does not support OGC requests, you need to handle all of the above interfaces. Depending on the business logic you are implementing there are two general approaches you can take.
If you are implementing an SOI that will perform security functions, then it is recommended that you begin by implementing all the above interfaces and blocking all requests. As you implement your custom code, you can logically allow access through the above interfaces. If you do not initially block incoming requests and subsequently allow access as desired, you run a greater risk of inadvertently exposing a security vulnerability.
If you are not implementing security functionality, you could implement the three interfaces by passing all requests through to the underlying standard implementation in order to allow normal functionality. Then subsequently add additional business logic to the one or more operations you want to enhance.
When a service is configured with an SOI, the server framework routes all service requests to the SOI. It is the responsibility of the SOI to filter the requests, delegate the request to the actual map or image service objects (if applicable), and then optionally further process the responses before returning it to the client.
Implementing layer-level access control
If you implement layer level-access control through an SOI, you'll also need to configure ArcGIS Server's REST handler to disable caching of all layer resources included the service. This will allow you to intercept operations and filter out layers which are not allowed. You can disable this by setting the service's disableCaching property to true in the ArcGIS Server Administrator Directory.
- Open the ArcGIS Server Administrator Directory and sign in. The URL is often formatted https://gisserver.domain.com:6443/arcgis/admin.
- Click services and click the name of the desired service. If you don't see it in the list, it may be located within a folder in this directory.
- Click edit.
- In the properties section of the service JSON, add the disableCaching property and set its value to true, for example:
"properties": { ... "disableCaching": "true", ... }, - Click Save Edits.
Creating an .soe file
Extensions (SOEs or SOIs) are encapsulated in an .soe file. The .soe file contains all the information necessary to register your extension with ArcGIS Server. If you're using .NET, the .soe file is created when you build your project from the template. If you're using Java, you'll create the .soe file using a wizard built into Eclipse. The .soe file can also be created using Esri's command line utilities that can be run manually or integrated into automated build scripts.
Extensions developed using the ArcGIS Enterprise SDK have the suffix _ent appended to their .soe file name. For example, an extension with the name SimpleRESTSOE would have the output file name SimpleRESTSOE_ent.soe.