SOE Web services

In this topic

About developing SOE Web services

ArcGIS Server 10 supports the development and deployment of custom server object extensions (SOEs) accessible as Representational State Transfer (REST) and Simple Object Access Protocol (SOAP) based Web services. Custom SOE functionality is exposed by the ArcGIS Server as Web services in the same way other native services (for example, map or geocode services) are exposed. 

SOEs run efficiently inside the geographic information system (GIS) server to make fine- grained calls to ArcObjects to implement the necessary geospatial functionality. Implementing the SOE to provide Web service access via REST or SOAP, eliminates the need for clients to utilize ArcObjects Component Object Model (COM) proxies. Basically, a client needs to know how to work with a REST or SOAP based Web service. In addition, an SOE Web service can leverage the management and security framework of ArcGIS Server, for example, securing access to an SOE Web service using the ArcGIS Server token service model.

ArcGIS Server supports developing SOAP and REST based SOEs in .NET or Java. An SOE can support one, the other, or both. SOEs developed in .NET, can be deployed with ArcGIS Server for Java. This section of the software development kit (SDK) describes building REST and SOAP Web services using .NET based SOEs and simple walkthroughs. Basically, the SOE provides a public method or operation to find features in feature layers (in a map) within a user-defined location and distance. While this basic geospatial functionality is already included in ArcGIS Server, implementing a service that does this, provides instructive details on SOE implementation for SOAP and REST.  

REST and SOAP SOE templates

ArcGIS provides a REST and a SOAP SOE template that are integrated with Visual Studio. These templates for developing REST and SOAP SOE Web services assist developers and save development time as they incorporate all the necessary code to implement the basic SOE functionality. Developers can start their SOE development with the template, then modify the existing code and add logic as required by their SOE. 
Currently, the templates are only available in C#.
Do the following steps to create a REST or SOAP SOE project based on the provided template:
  1. Start Visual Studio.
  2. Click the File menu, click New, then click Project. The New Project dialog box appears.
If your default Visual Studio settings are for VB .NET development, click the File menu, then click New Project to open the New Project dialog box.
  1. Under the Project types pane, click to expand the Visual C# node, then click to expand the ArcGIS node. See the following screen shot:

If your default Visual Studio settings are for VB .NET development, you will find the Visual C# section by first expanding the Other Languages option.
The REST SOE template application is comprised of a class that inherits ServicedComponent and implements all necessary interfaces, including IServerObjectExtension, IObjectConstruct, and IRESTRequestHandler. For more information on the REST SOE class implementation, see REST Web services.
The following screen shot shows the file structure of the generated REST SOE project:
The following screen shot shows the structure of the autogenerated code in the .cs file for the REST SOE:
The SOAP SOE template application is comprised of a class that inherits ServicedComponent and implements all the necessary interfaces, including IRequestHandler2, IServerObjectExtension, and IObjectConstruct. The other component in the structure is a template Web service description language (WSDL) file that developers can use to integrate ESRI SOAP types into their SOAP implementation. For more information on the SOAP SOE class implementation, see SOAP Web services.
The following screen shot shows the file structure of the generated SOAP SOE project:
The following screen shot shows the structure of the autogenerated code in the .vb file for the SOAP SOE:

Basic implementation

ArcGIS Server services represent "server objects" hosted in a GIS server container process.  The server object contains pre-packaged functionality associated with its purpose; therefore, map server objects host map data, generate map images, and handle queries; whereas, geocode server objects host a locator that assigns locations to addresses and visa versa.  
SOEs extend this functionality by using components that exist in the server object in a customized workflow. Access to this workflow is managed by one or more public methods in an SOE. While access to the SOE is possible on a local network using remote COM (Distributed Component Object Model [DCOM]) access, using standard protocols and formats via a Web service provides a more flexible solution for exposing SOE functionality to a wider audience outside the local network.  
The following illustration shows how SOEs are hosted and accessed via Web services. Clients discover how to work with an SOE defined in a standard contract, such as a Web Service Description Language (WSDL) for SOAP services and JavaScript Object Notation (JSON) for REST services. Clients send Web requests over Hypertext Transfer Protocol (HTTP) to a Web service hosted in an ArcGIS Server Web services instance. This instance contains a SOAP and REST handler to direct the request to an SOE hosted in a server object on the GIS server. The SOE deserializes the request, executes the business logic (usually accessing the server object), and serializes the response. The response is sent back to the client via the same HTTP channel and deserialized.

ArcGIS Server defines a set of ArcObjects interfaces that can be implemented by SOEs. One IServerObjectExtension, is required. All others are optional depending on the functionality you need to implement within the SOE. See the following tables:
Required interface
Description
IServerObjectExtension
This interface is used by the server object to manage the SOE's life span. The Init method is handed a reference to the hosting server object, which provides access to its resources. 
Optional interfaces
Description
IObjectConstruct
If your SOE includes configuration properties or requires additional initialization logic, implement IObjectConstruct. The Construct method is called only once, when the SOE is created, after IServerObjectExtension.Init. Include any expensive initialization logic within your implementation of Construct.
IObjectActivate
If your SOE requires logic to run each time server context is acquired and released (each time a request is handled), implement IObjectActivate.
 IRequestHandler2
Implement the HandleRequestString method to support SOAP interaction with the SOE.     
 IRESTRequestHandler
Implement the GetSchema and HandleRESTRequest methods to support REST interaction with the SOE. 

ArcGIS Server is built on the ArcObjects COM architecture. A .NET SOE class must be visible and accessible via COM to be used by ArcGIS Server. This is accomplished using the ComVisible and globally unique identifier (GUID) attributes. In addition, the class must derive from ServicedComponent to ensure it is created in the appropriated COM apartment. The ClassInterfaceType.None attribute tells type library generation tools that a default class interface does not need to be generated. The following code example shows a class declaration for a simple SOE class: 
[C#] 
[ClassInterface(ClassInterfaceType.None), GuidAttribute(
    "a9ed9e17-d2b2-461c-9da3-2915af9a3f00"), ComVisible(true)]
public class UtilSOE_CSharp: ServicedComponent, IServerObjectExtension
[VB.NET] 
<ClassInterface(ClassInterfaceType.None), GuidAttribute("a9ed9e17-d2b2-461c-9da3-2915af9a3f00"), ComVisible(True)> _
                Public UtilSOE_CSharp, IServerObjectExtension As Class

SOE capabilities

SOE methods can be grouped into capabilities. Each capability can be authorized on a per-configuration basis. Each call to an SOE includes the configuration capabilities and the method (operation) being called. Implementation of the SOE should check the capabilities to determine if a method can be executed. For example, assume an SOE has methods M1, M2, M3, and Capabilities C1 (which includes M1, M2) and C2 (including M1, M2, M3). When the SOE is enabled on a server object, the configuration only enables access to C1 capabilities. As a result, a call to M3 on the SOE should fail. 
Grouping methods into capabilities is optional.

ESRI.ArcGIS.SOESupport library

ArcGIS Server includes a native .NET library—ESRI.ArcGIS.SOESupport—to assist ArcGIS Server developers in defining and processing SOAP and REST content in an SOE. The library includes boiler-plate code for serialization and deserialization of messages, dispatching of business methods, error handling, and logging. In general, start with an implementation class—SoeRestImpl for REST and SoeSoapImpl for SOAP—to organize and define SOE functionality, and delegate calls to methods in the SOE. Use of the library will be discussed in the respective SOAP and REST sections. 

Debugging SOEs

Developers might need to test SOEs to make sure they operate as expected. SOEs are COM components that run inside the ArcGIS Server and hence, there are specific techniques for debugging an SOE.  
First, the SOE assembly must be registered with the /codebase option, which creates a codebase entry in the registry. The codebase entry specifies the file path for an assembly that is not installed in the global assembly cache (GAC). The assemblyFile argument that you specify with the /codebase option must be a strong-named assembly. For more information, see Strong-Named Assemblies on the Microsoft Developer Network (MSDN) Web site.
In the following code example, the SpatialQuerySOE.dll assembly is being registered with the /codebase option and should be signed with a strong name key file: 
regasm SpatialQuerySOE.dll /codebase
The following screen shot shows how to sign an assembly using the property page for a Visual Studio project. For more information on registering SOEs, see How to register the SOE.


Next, to debug the appropriate server object container (SOC), the ArcSOC.exe process sets the minimum and maximum number of instances for the service that hosts the SOE to a size of 1. This eliminates the chance that more than one SOC process for the service hosts your SOE. Also, you might want to stop all other services to reduce the number of SOCs you will need to select from when debugging. 
ArcGIS Server maintains two ArcSOC.exe processes. If there are many SOC processes running, and you do not want to stop them, attach the debugger to all the managed ArcSOC.exe processes for administration. They can be identified by a low memory footprint. 
Once you have the ArcGIS Server SOC machine ready where the SOE is enabled in a service that is running, attach the Visual Studio debugger to the ArcSOC.exe process. Do the following steps:
  1. Start Visual Studio and open the solution and project files containing the SOE implementation code.
  2. Click the Debug menu and select Attach to Process. See the following screen shot:
  1. After you click Attach to Process, the following screen shot appears listing all the available processes. If ArcSOC.exe processes are not listed, select the Show processes from all users and Show processes in all sessions check boxes. Find all the ArcSOC.exe processes with Managed , x86 in the Type column. If there are more than one, determine which one is associated with the service hosting the SOE. In this example, there is only one managed instance available.


  2. After selecting the ArcSOC.exe process or processes, click the Attach button on the preceding screen shot. The Attach Security Warning dialog box appears. Since this is a genuine testing scenario, it is safe to click Attach. See the following screen shot:
 
  1. Place a breakpoint in the SOE source code. See the following screen shot:

  1. Open the SOE client and initiate a request to call the SOE logic for which a breakpoint was added. For example, the Spatial Query SOE sample uses a Web application client to show the SOE in action. The Web application contains a tool that calls SOE logic on the server. The sample is located at <ArcGIS DeveloperKit install location>/Samples/ArcObjectsNet/ServerSpatialQuery. See the following screen shot:

  1. Select the Vegetation Summary Proximity Search Tool, then click the map. This action triggers the function in the SOE and the breakpoint will be hit. See the following screen shot:

  1. During execution, the breakpoint in the SOE source code is hit and you can progress through the SOE logic as needed. Once debugging of the SOE is terminated or stopped, Visual Studio detaches from the ArcSOC.exe. 
  2. If you need to change to the SOE source code and you registered the SOE using the codebase option mentioned at the beginning of this section, stop the ArcGIS Server services that use the SOE, change the SOE source code, rebuild, then start the services again. It is not necessary to register again (regasm) or re-add to the GAC.