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 the SOE or SOI's Maven archetype. If you're working in .NET, you'll start in Visual Studio with a template project. The 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 ArcGIS Enterprise SDK documentation.
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 must implement the following interfaces:
- IRESTRequestHandler for handling REST API requests
- IRequestHandler for handling SOAP API requests, including requests made by ArcGIS Pro
- IWebRequestHandler for handling OGC requests
Even if a particular service configuration does not support OGC requests, you must handle all of the above interfaces. Depending on the business logic you are implementing, there are two general approaches you can take.
Note:
If a map or image service contains cached tiles, requests made to those tiles cannot be intercepted.
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.
Implement layer-level access control
If you implement layer-level access control through an SOI, you'll also need to configure the ArcGIS GIS 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 GIS Server Administrator Directory.
- Open the ArcGIS GIS 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 GIS Server. If you're using .NET, the .soe file is created when you build your project. If you're using Java, you'll create the .soe file by building the Maven SOE or SOI project. The .soe file can also be created using the mvn install command 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.