How to develop the REST SOE

In this topic

• About developing the REST SOE
• Creating an SOE from the Visual Studio template
• Modifying the SOE attributes
• Adding variables
  • Examining the SOE constructor
• Implementing IServerObjectExtension
• Implementing IObjectConstruct
• Implementing IRESTRequestHandler
• Modifying the CreateRestSchema function
• Modifying the RootResHandler function
• Modifying the operation handler function
• Adding helper functions QueryPoint and CreateJsonRecords
• Signing and building the project

About developing the REST SOE

Creating an SOE from the Visual Studio template

1. Start Visual Studio.
2. Click File, New, then Project. The New Project dialog box appears.
3. Under the Installed Templates area, expand the Visual C#, ArcGIS, Server Object Extensions nodes.  
4. Click the REST Template.
5. Type SpatialQueryREST in the Name field and click OK.
6. In the Solution Explorer, double-click SpatialQueryREST.cs and review the template code.

Modifying the SOE attributes

• FieldName
• LayerName

[C#]

[ServerObjectExtension("MapServer", AllCapabilities="", DefaultCapabilities="",
    Description="", DisplayName="SpatialQueryREST", Properties="",
    SupportsREST=true, SupportsSOAP=false)]

[C#]

[ServerObjectExtension("MapServer", AllCapabilities="", DefaultCapabilities="",
    Description="Spatial Query REST SOE Sample", DisplayName="SpatialQueryREST",
    Properties="FieldName=PRIMARY_;LayerName=veg", SupportsREST=true,
    SupportsSOAP=false)]

Adding variables

• Feature class to be queried
• Layer name of that feature class
• Field on which the area summary will be based

[C#]

private IPropertySet configProps;
private IServerObjectHelper serverObjectHelper;
private ServerLogger logger;
private IRESTRequestHandler reqHandler;

[C#]

private IFeatureClass m_fcToQuery;
private string m_mapLayerNameToQuery;
private string m_mapFieldToQuery;

Examining the SOE constructor

Implementing IServerObjectExtension

[C#]

public void Shutdown(){}

[C#]

public void Shutdown()
{
    logger.LogMessage(ServerLogger.msgType.infoStandard, "Shutdown", 8000, 
        "Custom message: Shutting down the SOE");
    soe_name=null;
    m_fcToQuery=null;
    m_mapFieldToQuery=null;
    serverObjectHelper=null;
    logger=null;
}

Implementing IObjectConstruct

[C#]

public void Construct(IPropertySet props)
{
    configProps=props;
}

[C#]

public void Construct(IPropertySet props)
{
    configProps=props;
    // Read the properties.

    if (props.GetProperty("FieldName") != null)
    {
        m_mapFieldToQuery=props.GetProperty("FieldName")as string;
    }
    else
    {
        throw new ArgumentNullException();
    }
    if (props.GetProperty("LayerName") != null)
    {
        m_mapLayerNameToQuery=props.GetProperty("LayerName")as string;
    }
    else
    {
        throw new ArgumentNullException();
    }
    try
    {
        // Get the feature layer to be queried.
        // Since the layer is a property of the SOE, this only has to be done once.
        IMapServer3 mapServer=(IMapServer3)serverObjectHelper.ServerObject;
        string mapName=mapServer.DefaultMapName;
        IMapLayerInfo layerInfo;
        IMapLayerInfos layerInfos=mapServer.GetServerInfo(mapName).MapLayerInfos;
        // Find the index position of the map layer to query.
        int c=layerInfos.Count;
        int layerIndex=0;
        for (int i=0; i < c; i++)
        {
            layerInfo=layerInfos.get_Element(i);
            if (layerInfo.Name == m_mapLayerNameToQuery)
            {
                layerIndex=i;
                break;
            }
        }
        // Use IMapServerDataAccess to get the data
        IMapServerDataAccess dataAccess=(IMapServerDataAccess)mapServer;
        // Get access to the source feature class.
        m_fcToQuery=(IFeatureClass)dataAccess.GetDataSource(mapName, layerIndex);
        if (m_fcToQuery == null)
        {
            logger.LogMessage(ServerLogger.msgType.error, "Construct", 8000, 
                "SOE custom error: Layer name not found.");
            return ;
        }
        // Make sure the layer contains the field specified by the SOE's configuration.
        if (m_fcToQuery.FindField(m_mapFieldToQuery) ==  - 1)
        {
            logger.LogMessage(ServerLogger.msgType.error, "Construct", 8000, 
                "SOE custom error: Field not found in layer.");
        }
    }
    catch 
    {
        logger.LogMessage(ServerLogger.msgType.error, "Construct", 8000, 
            "SOE custom error: Could not get the feature layer.");
    }
}

• Get all the layer information (IMapLayerInfos) from this map service (IMapServer3).
• Iterate through all the layer information and get the layer of interest (which was designated in the SOE properties).
• Get the data source (IFeatureClass) for the layer of interest.
  

Implementing IRESTRequestHandler

• GetSchema—You don't need to alter this code unless you want to put a log message here.
• HandleRESTRequest—You don't need to change this code either.

Modifying the CreateRestSchema function

[C#]

private RestResource CreateRestSchema()
{
    RestResource rootRes=new RestResource(soe_name, false, RootResHandler);
    RestOperation sampleOper=new RestOperation("sampleOperation", new string[]
    {
        "parm1", "parm2"
    }
    , new string[]
    {
        "json"
    }
    , SampleOperHandler);
    rootRes.operations.Add(sampleOper);
    return rootRes;
}

[C#]

private RestResource CreateRestSchema()
{
    RestResource rootRes=new RestResource(soe_name, false, RootResHandler);
    RestOperation spatialQueryOper=new RestOperation("SpatialQuery", new string[]
    {
        "location", "distance"
    }
    , new string[]
    {
        "json"
    }
    , SpatialQueryOperationHandler);
    rootRes.operations.Add(spatialQueryOper);
    return rootRes;
}

Modifying the RootResHandler function

[C#]

result.AddString("hello", "world");

Modifying the operation handler function

[C#]

private byte[] SampleOperHandler(NameValueCollection boundVariables, JsonObject
    operationInput, string outputFormat, string requestProperties, out string
    responseProperties)
{
    responseProperties=null;
    string parm1Value;
    bool found=operationInput.TryGetString("parm1", out parm1Value);
    if (!found || string.IsNullOrEmpty(parm1Value))
        throw new ArgumentNullException("parm1");
    string parm2Value;
    found=operationInput.TryGetString("parm2", out parm2Value);
    if (!found || string.IsNullOrEmpty(parm2Value))
        throw new ArgumentNullException("parm2");
    JsonObject result=new JsonObject();
    result.AddString("parm1", parm1Value);
    result.AddString("parm2", parm2Value);
    return Encoding.UTF8.GetBytes(result.ToJson());
}

[C#]

private byte[] SpatialQueryOperationHandler(NameValueCollection boundVariables,
    JsonObject operationInput, string outputFormat, string requestProperties, out
    string responseProperties)
{
    responseProperties=null;
    // Deserialize the location.
    JsonObject jsonPoint;
    if (!operationInput.TryGetJsonObject("location", out jsonPoint))
        throw new ArgumentNullException("location");
    IPoint location=Conversion.ToGeometry(jsonPoint,
        esriGeometryType.esriGeometryPoint)as IPoint;
    if (location == null)
        throw new ArgumentException("SpatialQueryREST: invalid location", "location")
            ;
    // Deserialize the distance.
    double ? distance;
    if (!operationInput.TryGetAsDouble("distance", out distance) ||
        !distance.HasValue)
        throw new ArgumentException("SpatialQueryREST: invalid distance", "distance")
            ;
    byte[] result=QueryPoint(location, distance.Value);
    return result;
}

Adding helper functions QueryPoint and CreateJsonRecords

• QueryPoint
• CreateJsonRecords

[C#]

private byte[] QueryPoint(ESRI.ArcGIS.Geometry.IPoint location, double distance)
{
    if (distance <= 0.0)
        throw new ArgumentOutOfRangeException("distance");
    // Buffer the point.
    ITopologicalOperator topologicalOperator=
        (ESRI.ArcGIS.Geometry.ITopologicalOperator)location;
    IGeometry queryGeometry=topologicalOperator.Buffer(distance);
    // Query the feature class.
    ISpatialFilter spatialFilter=new ESRI.ArcGIS.Geodatabase.SpatialFilter();
    spatialFilter.Geometry=queryGeometry;
    spatialFilter.SpatialRel =
        ESRI.ArcGIS.Geodatabase.esriSpatialRelEnum.esriSpatialRelIntersects;
    spatialFilter.GeometryField=m_fcToQuery.ShapeFieldName;
    IFeatureCursor resultsFeatureCursor=m_fcToQuery.Search(spatialFilter, true);
    // Loop through the features, clip each geometry to the buffer,
    // and total areas by attribute value.
    topologicalOperator=(ESRI.ArcGIS.Geometry.ITopologicalOperator)queryGeometry;
    int classFieldIndex=m_fcToQuery.FindField(m_mapFieldToQuery);
    // System.Collections.Specialized.ListDictionary summaryStatsDictionary=new System.Collections.Specialized.ListDictionary();
    Dictionary < string, double > summaryStatsDictionary=new Dictionary < string,
        double > ();
    // Initialize a list to hold JSON geometries.
    List < JsonObject > jsonGeometries=new List < JsonObject > ();

    IFeature resultsFeature=null;
    while ((resultsFeature=resultsFeatureCursor.NextFeature()) != null)
    {
        // Clip the geometry.
        IPolygon clippedResultsGeometry=(IPolygon)topologicalOperator.Intersect
            (resultsFeature.Shape,
            ESRI.ArcGIS.Geometry.esriGeometryDimension.esriGeometry2Dimension);
        clippedResultsGeometry.Densify(0, 0); 
            // Densify to maintain curved appearance when converted to JSON. 
        // Convert the geometry to JSON and add it to the list.
        JsonObject jsonClippedResultsGeometry=Conversion.ToJsonObject
            (clippedResultsGeometry);
        jsonGeometries.Add(jsonClippedResultsGeometry);
        // Get statistics.
        IArea area=(IArea)clippedResultsGeometry;
        string resultsClass=resultsFeature.get_Value(classFieldIndex)as string;
        // If the class is already in the dictionary, add the current feature's area to the existing entry.
        if (summaryStatsDictionary.ContainsKey(resultsClass))
            summaryStatsDictionary[resultsClass]=(double)
                summaryStatsDictionary[resultsClass] + area.Area;
        else
            summaryStatsDictionary[resultsClass]=area.Area;
    }
    // Use a helper method to get a JSON array of area records.
    JsonObject[] areaResultJson=CreateJsonRecords(summaryStatsDictionary)as
        JsonObject[];
    // Create a JSON object of the geometry results and the area records.
    JsonObject resultJsonObject=new JsonObject();
    resultJsonObject.AddArray("geometries", jsonGeometries.ToArray());
    resultJsonObject.AddArray("records", areaResultJson);
    // Get byte array of json and return results.
    byte[] result=Encoding.UTF8.GetBytes(resultJsonObject.ToJson());
    return result;
}

// Helper method to read the items in a dictionary and make a JSON object from them.
private JsonObject[] CreateJsonRecords(Dictionary < string, double >
    inListDictionary)
{
    JsonObject[] jsonRecordsArray=new JsonObject[inListDictionary.Count];
    int i=0;
    // Loop through dictionary.
    foreach (KeyValuePair < string, double > kvp in inListDictionary)
    {
        // Get the current key and value.
        string currentKey=kvp.Key.ToString();
        string currentValue=kvp.Value.ToString();
        // Add the key and value to a JSON object.
        JsonObject currentKeyValue=new JsonObject();
        currentKeyValue.AddString(m_mapLayerNameToQuery, currentKey);
        currentKeyValue.AddString("value", currentValue);
        // Add the record object to an array.
        jsonRecordsArray.SetValue(currentKeyValue, i);
        i++;
    }

    return jsonRecordsArray;
}

• Buffers the input point by the user-specified distance
• Queries all the vegetation polygons that intersect the buffer
• Loops through each polygon and clips it to the buffer outline
• Converts the clipped polygon to a JSON object and adds it to a .NET list
• Sums the area of the clipped polygon and adds the area to a dictionary
• After looping through all polygons, serializes the clipped polygons and the area stats into one JSON object, and returns that JSON object to the user

Signing and building the project

1. In the Solution Explorer, right-click the SpatialQueryREST project and click Properties.
2. Click the Signing tab and ensure the "Sign the assembly" check box is selected. 
3. In the "Choose a strong name key file" area, choose to use either the key file included with the template mykey.snk or create your own key. Click mykey.snk in the drop-down list to see the New and Browse options.
4. Save your project.
5. In the Solution Explorer, right-click your project and click Build. This creates SpatialQueryREST.dll and SpatialQueryREST.soe in your project's bin\debug or bin\release folder.

See Also:

Walkthrough: Creating a REST server object extension
How to deploy the REST SOE
How to develop a property page for the REST SOE
How to enable and test the REST SOE on a service
How to use the REST SOE in a Web application
Sample: Spatial Query REST SOE