Creating a server object extension

Click here to get the sample associated with this walkthrough.

In this topic

Project description

This walkthrough topic is for developers who need to build and deploy a server object extension (SOE) to use in server applications. The process of extending the MapServer to provide methods for performing a specific type of spatial analysis on the features in one map layer is described. 
This topic (first section) is divided into the following associated topics that you need to use to complete the information in the entire walkthrough:

This topic also has the following associated sample: 
The purpose of this topic is to create an SOE using C# to extend a MapServer server object. The SOE exposes methods to clip the geometries of polygons in one of the layers on the map to a buffer around a user-defined point. Summary statistics are provided using the area of the clipped polygons based on the unique values of a specified field. The layer to perform the analysis on and the field to summarize statistics on are properties of the SOE.
As part of this walkthrough topic, you will create custom administration property pages—one for ArcCatalog and one for ArcGIS Server Manager—that allow you to set the SOE's layer and field properties based on the MapServer object's map document. Finally, you will create a client Web application that consumes your SOE. This application utilizes the Web Application Developer Framework's (ADF's) controls and capabilities.

Concepts

Both coarse-grained calls to remote ArcObjects—such as the methods on the MapServer and GeocodeServer—as well as fine grained calls to remote ArcObjects—such as looping through all the vertices of a polygon—are exposed through the ArcGIS Server ArcObjects application programming interface (API) and can be used in your application. When making a call against an object running in the server from your Web application, you are making that call across processes. The Web application is running in one process, while the object is running in another process.
Calls to objects across processes are significantly slower than calls to objects in the same process. It is possible that your Web application is running on a Web server that is a different machine from the one the object is running on; therefore, the calls are not only cross process but also cross machine.
If your application requires making a large number of fine-grained ArcObjects calls, the following are strategies you can employ to extend the geographic information system (GIS) server with your object, both of which expose coarse-grained interfaces:
  • Create utility Component Object Model (COM) objects
  • Create SOEs
Extending a server object has the following advantages over creating a generic COM object:
  • Developers do not need to explicitly create instances of an SOE in a context. The SOE is created by the GIS server when the server object instance is created.
  • If the functionality that is exposed by the extension requires resources that can be costly to acquire, the initialization cost of creating the object is paid once when the server object and its extensions are initially created.
  • If the functionality that is exposed by the extension can benefit from caching logic, it is possible to implement the logic because the cache remains for as long as the server object instance remains in the pool.
  • ArcGIS Server administration applications (that is, ArcCatalog and ArcGIS Server Manager) can be extended to include custom property dialog boxes to configure custom extensions for specific server object configurations.
  • An SOE can utilize ArcGIS Server log files to provide status and troubleshooting content, like other ArcGIS Server components. 
Unlike utility COM objects, SOEs are registered and configured with specific server objects and are not for ad hoc use or use with an empty server context. For more information on extending the GIS server with utility COM objects, see the sample Server spatial query COM utility.
The SOE meets application requirements for functionality that needs to make a large number of fine-grained ArcObjects calls within the ArcGIS Server container process (ArcSOC.exe). In this case, these calls include looping through features, getting the geometry, clipping the geometry, summarizing the areas of the geometries based on an attribute, creating a graphic for each feature, and so on. Since the caller of the SOE is free to specify a buffer distance that can include a large number of features, the number of features that can be analyzed is indeterminate, which can easily result in thousands of fine-grained ArcObjects calls.

Design

The SOE in this topic extends the MapServer with specialized functionality exposed as a stateless method on a custom interface. As a result, configure the SOE with a pooled MapServer. The SOE stores two custom properties with the MapServer configuration for which the extension is enabled. The following properties are used during execution and can be set through custom property pages for ArcCatalog and ArcGIS Server Manager:
  • LayerName—Layer name in the MapServer's map document that contains the features on which to perform the analysis.
  • FieldName—Field name in the layer for which the clipped polygons' areas are summarized.
The Web application makes stateless use of the GIS server. The application uses events on the Web ADF Map control to get a point from the user, gains access to server context using the MapResource for an ArcGIS Server Local data source, then uses the point as input to the SOE to perform the analysis. To support this application, add a pooled map server object to your ArcGIS Server, then use ArcCatalog or ArcGIS Server Manager to enable the custom SOE on the server object.
The Web application uses the Web ADF to manage the connection to the GIS server and the Web ADF's controls provide the required basic mapping functionality for the application. You will add a new tool to the Toolbar control that allows the user to click the map and provide the input to the analysis. The results show on the map as a set of graphics and are summarized in a table on the Web page.

Requirements

To follow the steps in this walkthrough, you need ArcGIS Server and ArcGIS Desktop installed and running. The machine on which you develop the Web application must, at a minimum, have the Web ADF, .NET software development kit (SDK), and Internet Information Services (IIS) installed.
The following ArcObjects .NET assemblies are used to build the SOE and property pages:
  • ESRI.ArcGIS.Carto
  • ESRI.ArcGIS.Catalog
  • ESRI.ArcGIS.CatalogUI
  • ESRI.ArcGIS.Display
  • ESRI.ArcGIS.Framework
  • ESRI.ArcGIS.Geodatabase
  • ESRI.ArcGIS.Geometry
  • ESRI.ArcGIS.Server
  • ESRI.ArcGIS.System
  • ESRI.ArcGIS.ServerManager
The following .NET framework assembly is also required:
  • System.EnterpriseServices
The following ArcObjects and Web ADF .NET assemblies are used to build the Web application:
  • ESRI.ArcGIS.Carto
  • ESRI.ArcGIS.Geodatabase
  • ESRI.ArcGIS.Geometry
  • ESRI.ArcGIS.Server
  • ESRI.ArcGIS.ADF.Web.UI.WebControls
  • ESRI.ArcGIS.ADF.Web.UI.WebControls.Tools
  • ESRI.ArcGIS.ADF.Web.DataSources
  • ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer
  • ESRI.ArcGIS.ADF.ArcGISServer
The development environment does not require ArcGIS licensing; however, connecting to a server and using a map server object does require that the GIS server is licensed to run ArcObjects on the server. None of the assemblies or object libraries used require an extension license.
The integrated development environment (IDE) used in this topic is Visual Studio 2008; therefore, all IDE specific steps assume that is the IDE you are using.

Implementation

The code for this walkthrough topic is divided into the following sections: 
  • Implementation of the SOE—Runs within the GIS server and exposes the methods that extend the MapServer server object (discussed in How to develop the SOE). 
  • SOE property pages—One will be registered with the ArcCatalog desktop application and the other will be registered with the ArcGIS Server Manager Web application (discussed in How to create SOE property pages).
  • Utility application—Registers the SOE with the GIS Server (discussed in How to register the SOE). 
  • Web application—Creates a Web application that uses the SOE, and the Web ADF controls and APIs (discussed in How to create an SOE client).

Additional resources

This topic includes functionality and programming techniques that cover a number of different aspects of ArcObjects, ArcGIS Server ArcObjects API, ArcGIS Server Simple Object Access Protocol (SOAP) API, Web ADF Common API, and Web controls.
For more information about core ArcGIS Server programming concepts, such as stateful versus stateless server application environment, see Developing with ArcGIS Server.
This topic also covers concepts and programming guidelines to work with server contexts and ArcObjects running within those contexts, as well as a discussion on extending server objects.
This topic uses the Web ADF to provide the majority of the user interface (UI) for this Web application. For more information about the Web ADF, which includes descriptions and examples of using Web controls (including the Map and Toolbar controls) that you will use while programming this Web application, see the ArcGIS Server Help system for .NET under the following nodes in the table of contents (TOC):
  • Creating ArcGIS Server solutions, Developing Web applications using Web ADF
If you are unfamiliar with ASP.NET Web development, refer to your .NET developer Help to become more familiar with Web application development.
ArcGIS Server applications exploit the rich GIS functionality of ArcObjects and this application is no exception. It uses ArcObjects to work with the components of a MapServer, buffer and clip geometries, geodatabase query, and graphic creation. For more information about these aspects of ArcObjects, see the following object libraries in the ArcObjects Help system:


See Also:

How to develop the SOE
How to create SOE property pages
How to register the SOE
How to create an SOE client