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 extensions 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
You can use ArcGIS Enterprise SDK to develop server object extensions (SOEs) to extend map services and to develop server object interceptors (SOIs) to customize the functions of map services (including service extensions such as feature services and OGC-compliant services).
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, depending on whether you are implementing security or nonsecurity-related functionality.
Intercepting REST, SOAP, and OGC service requests
Map and image services support three types of requests:
- REST API requests
- SOAP API requests
- OGC requests
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 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, 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 to allow normal functionality. Then subsequently add additional business logic to the 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 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 the ArcGIS Server REST handler to disable caching of all layer resources included in the service. This will allow you to intercept operations and filter out layers that 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 in 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.