Simple REST SOE


Purpose
This sample illustrates the basic framework for creating a server object extension (SOE) that will be hosted as an ArcGIS Server Representational State Transfer (REST) Web service. The SOE extends the functionality of a map service with a single operation to echo input text. Only map services can be extended with REST SOEs.
 
This sample is divided into two parts: the SOE implementation, which receives REST messages, processes requests, and generates REST responses; and the registration application, which registers the SOE with ArcGIS Server.
 
ArcGIS provides a REST SOE template (currently only available in C#) that is integrated with Visual Studio. For more information, see SOE Web services.

How to use

See How to use ArcGIS samples for help on compiling, setting up the debugger, and running the sample. If the sample has associated data, you will find that the sample's zip file includes a "data" folder alongside the language folders. However, you will need to update the sample to point to the location of the data once you have extracted all the files.

Build and register the SOE
  1. Verify that ArcGIS Server for .NET is installed and functioning properly.
  2. Browse to the <ArcGIS DeveloperKit install location>\Samples\ArcObjectsNET\ServerSimpleRESTSOE folder. It contains two folders, CSharp and VBNet. The instructions herein correspond to the CSharp version. To set up the VB .NET version, the steps are the same, except the assemblies generated using VB .NET are suffixed with "_VBNet" (for example, the solution file under the VBNet folder would be SimpleRestSOE_VBNet2008.sln).
  3. Start Microsoft Visual Studio and open the SimpleRESTSOE<vs_version> solution (for example, SimpleRESTSOE2008.sln). The <vs_version> references the Visual Studio version of the solution.
  4. Under the Build menu, select Build Solution. One assembly is created. The SimpleRESTSOE.dll file is created in the \bin\Debug or the \bin\Release folder.
  5. Open a Visual Studio command prompt and navigate to the location of the SimpleRESTSOE.dll file. This assembly contains a class that needs to be accessible by a Component Object Model (COM)-aware client, such as ArcObjects running in a server object container (SOC) process (ArcSOC.exe). To register the .NET assembly with COM, use this command: regasm SimpleRESTSOE.dll /codebase.
  6. Verify that the ArcGIS SOC (for example, ArcGISSOC) account has read access to this location.

Register the SOE with ArcGIS Server
  1. In Visual Studio, set the RegisterSimpleRESTSOE project as the active project (or open the project).
  2. On the Debug menu, select Start Debugging. If successful, the console window displays a message indicating the SOE was registered with ArcGIS Server. The application must run as a user with administrative access to ArcGIS Server (user must be part of the agsadmin group on the Server Object Manager machine). By default, the application uses the current Windows account under which Visual Studio is running.
  3. Start ArcCatalog and open an administrative connection to the ArcGIS Server instance on which the SOE was registered. If you're working with all components on the same machine, use the local machine name or "localhost."
  4. Create a new map service. The USA sample data included with the software development kit (SDK) (<ArcGIS Developer Kit Location>\Samples\data\Usa) can be used.
  5. Define a name and the appropriate parameters for a new map service. If you're modifying an existing map service, stop the service and proceed to the next step.
  6. On the Capabilities tab, scroll to the bottom of the window in the upper left corner of the dialog box and select the Simple REST SOE check box.
  7. Finish configuring the service and start it.

Explore the SOE in ArcGIS Server Services Directory
  1. Open a browser and navigate to the root REST services endpoint for an ArcGIS Server Web services instance hosting your ArcGIS Server services (for example: http://localhost/arcgis/rest/services). You'll see a list of services, including the map service created in the previous section.
  2. Click the map service created in the previous section and scroll to the bottom of the map service description page. The section titled Supported Extensions includes the SOE SimpleRESTSOE.
  3. Click the SOE name. The REST SOE description page displays one supported operation: echo.
  4. Click the operation to display the interactive dialog box to define text to send and return from the SOE.
  5. Click the echo button to initiate the request. A response containing the input text is returned.

SimpleRESTSOE\SimpleRESTSOE.cs Core SOE implementation for REST Web service.
RegisterSimpleRESTSOE\Program.cs Console application to register the SOE with ArcGIS Server.
Download the C# files
SimpleRESTSOE_VBNet\SimpleRESTSOE_VBNet.vb Core SOE implementation for REST Web service.
RegisterSimpleRESTSOE_VBNet\Program.vb Console application to register the SOE with ArcGIS Server.
Download the VB.NET files

Download the files for all languages