Quick tour of the REST server object extension template (ArcObjects .NET 10.8 SDK)

About the REST server object extension template

This topic explains some of the code you'll see in the Representational State Transfer (REST) server object extension (SOE) template that's included in Visual Studio when you install the .NET ArcObjects software development kit (SDK). For more information on how to open the template, see How to open the REST server object extension template in Visual Studio.

It's important to remember that an SOE is a Component Object Model (COM) class that resides on your server. So, you have a few lines related to COM that give your SOE a unique ID and make it visible to COM. You'll also see some attributes for your SOE, where you can define its display name, properties, and capabilities (sometimes called "Operations allowed" in the ArcGIS dialog boxes) See the following code example:

[C#]

[ComVisible(true)][Guid("fbcd47be-14e5-4c65-b49d-7cdb6871f30a")][ClassInterface
    (ClassInterfaceType.None)][ServerObjectExtension("MapServer", AllCapabilities=
    "", DefaultCapabilities="", Description="Insert SOE Description here",
    DisplayName="SimpleRestSoe1", Properties="", SupportsREST=true,
    SupportsSOAP=false)]

[VB.NET]

<ServerObjectExtension("MapServer", AllCapabilities
= "", DefaultCapabilities
= "", _
  Description
= "Insert SOE Description here", DisplayName
= "SimpleRestSoe1", _
  Properties
= "", SupportsREST
= True, SupportsSOAP
= False)>

You don't have to do anything with this code. The globally unique identifier (GUID) is generated for you when you create a project.

You'll also notice that your SOE class implements a number of interfaces, some of which might be new to you. See the following code example:

[C#]

public class SimpleRestSoe1: IServerObjectExtension, IObjectConstruct,
    IRESTRequestHandler

[VB.NET]

Public Class RestSOE1
    Implements IServerObjectExtension, IObjectConstruct, IRESTRequestHandler

All of these interfaces are required for building a REST SOE. The following describes what the interfaces do:

IServerObjectExtension - Contains Init() and Shutdown() methods that start up and shut down your SOE. You don't have to alter these from the template, unless there's something you specifically want to destroy on shutdown. If you have business logic that you want to run when the SOE first becomes enabled, don't put it in Init() or in your SOE class's constructor; instead, use the following IObjectConstruct.Construct() method.
IObjectConstruct - Contains one method, Construct(), that runs when your SOE is first enabled. This is where you put any expensive business logic that you don't need to run on each request. For example, if you know you're always working with the same layer in the map, you can put the code to get the layer here.
IRESTRequestHandler - Allows for REST requests and responses to come into the service. These methods create the schema and handle the requests. In the template, you can generally leave this code alone.

Moving down to the SOE constructor, you'll notice the class SoeRestImpl being used. See the following code example:

[C#]

reqHandler=new SoeRestImpl(soe_name, CreateRestSchema())as IRESTRequestHandler;

[VB.NET]

Dim restImpl As New SoeRestImpl(c_SOEName, rootResource)
reqHandler=CType(restImpl, IRESTRequestHandler)

The SoeRestImpl class has code to do the following:

Validate the SOE schema
Validate the resourceName and operationName of the HandleRESTRequest calls
Validate SOE capabilities
Log the service calls and responses
Handle errors

SoeRestImpl implements IRESTRequestHandler. Normally, the SOE class contains an instance of the SoeRestImpl class and keeps a reference to the IRESTRequestHandler interface. You can see this later in the template.

The remainder of the template contains some stubbed out functions for defining what the REST SOE can do and how each request to the SOE should be handled. CreateRestSchema() defines the resources and operations available in your SOE. Each of these resources and operations has an associated handler function that describes what to do when the resource or operation is invoked. The template contains one sample resource handler, RootResHandler(), and one sample operation handler, SampleOperHandler().