Sunday, November 2, 2008

ArcGIS Server: Expose a custom server object extension via SOAP

Extending ArcGIS Server using ArcObjects can take two forms: a utility COM object or a server object extension. A utility COM object is simply a COM component created and managed explicitly in server context. A server object extension (SOE) is coupled with a server object and thus can share initialization, resource utilization, and disposal. Use of a COM utility has been possible since the first version of ArcGIS Server (9.0). Custom SOEs were introduced for ArcGIS Server .NET at version 9.2. ArcGIS Server Java does not offer an SOE solution at the moment, but it is likely forthcoming. The reasons for extending ArcGIS Server and differences between both techniques are available elsewhere so I'll skip that discussion here. I want to discuss exposing ArcObjects logic in a custom server object extension via a prepackaged ArcGIS Server Web service handler. Two major protocols are supported, SOAP and REST. Let's dive in...

The ArcGIS Server SOAP API is implemented at the server object level. This means that SOAP messages are processed directly by a server object or extension (SOE). The ArcGIS Server SOAP Web service handler directs SOAP messages to a server object for you. The ArcGIS Server REST API is not implemented at the server object level. The ArcGIS Server REST Web service handler processes restful requests and (in general) uses the ArcGIS Server SOAP API to communicate with ArcGIS Server. How does this relate to exposing a custom SOE as a Web service? The SOAP Web service handler contains logic to discover custom SOEs with a SOAP interface (see sample and discussion below). The REST Web service handler does not contain the logic to discover custom SOEs at this time. Consequently, to expose a custom SOE as a REST service you’ll need to create your own Web service to handle restful requests and work with the SOE. Unfortunately this means you'll need to work with ArcObjects remotely in the Web service logic, which will require an ArcGIS Server license in the app-tier... a less than optimal solution. The folks at ESRI who work on the REST handler may resolve this in the future.

I've included a sample that illustrates how to expose a custom SOE via the ArcGIS Server SOAP Web service handler. It builds on the current
Server SDK sample which shows how to create a simple SOE.

I’ve modified this sample to illustrate how to support exposing a custom SOE using an ArcGIS Server Web service endpoint. The sample is merely instructive, so it just provides the basics of custom SOE development. To expose a WSDL for the custom SOE and make it available via an ArcGIS Server Web service endpoint, create a WSDL and put it in the \XmlSchema folder on the machine where the SOM is running. The name of the registered server object extension and the name of the *.wsdl file must be the same. To process SOAP requests, implement the IRequestHandler and IRequestHandler2 interfaces in the custom SOE class. In this example, the implementation code parses the incoming SOAP request and generates a raw SOAP response string. The response should match the WSDL definition.

Download the sample here.

Everything is pretty raw and simple at the moment, but it works. I’m sure there’s a better way to create the WSDL and generate SOAP responses, but that’ll take some additional research. Once the custom SOE is deployed and enabled on a map service, you can use the following url to get the WSDL: http://localhost/arcgis/services/<service name>/MapServer/SimpleSOE_CSharp?wsdl


matej said...

Hi, is there another way than parse XML request to process complex SOAP data types (e.g. MapDescription) sent to HandleStringRequest method of SOE?
When do you expect the possibility of accessing SOE thru REST as you mentioned in your post?

NicoGis said...

Matej, Have you used linq to xml so it's very easy...

ShailGIS said...

Nice work ... This actually gave me some hopes over SOE to SOAP and ways to handle the internet resources.

When i typed the URL in the browser to see the SOAP, i get the following error.
http://localhost/arcgis/services/my servicename/MapServer/SimpleSOE_CSharp?wsdl

Server Error in '/ArcGIS/services' Application.
Error HRESULT E_FAIL has been returned from a call to a COM component.
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.

Exception Details: System.Web.HttpException: Error HRESULT E_FAIL has been returned from a call to a COM component.

Source Error:

An unhandled exception was generated during the execution of the current web request. Information regarding the origin and location of the exception can be identified using the exception stack trace below.

Stack Trace:

[HttpException (0x80004005): Error HRESULT E_FAIL has been returned from a call to a COM component.]

rex hansen said...


As far as parsing XML is concerned, LINQ (as NicoGis mentioned) and the standard .NET XmlTextReader will work. From ESRI's perspective, a new Message class was provided with 9.3 to assist with parsing. It's not documented very well, so I've included a sample code snippet below. I construct a SOAP message for the sake of the example.

On the SOE-REST front, ESRI may provide a means for accessing a custom SOE via the ArcGIS Server REST services in 9.4. In the meantime, you can create your own REST service implementation (e.g. asmx, wcf, httphandler, etc.) that wraps working with your SOE. Granted it will be not be discoverable using ArcGIS Services Directory and not accessible via the well-known ArcGIS Server REST endpoint... but it is technically possible, and legal. You would need to license the machine(s) to use ArcObjects remotely. The Web ADF runtime gives you what you need in the smallest install package available.

StringBuilder sb = new StringBuilder();

sb.Append("<?xml version='1.0' encoding='utf-8'?>");
sb.Append("<soap:Envelope xmlns:soap='' xmlns:xsi='' xmlns:xsd=''>");
sb.Append("<SomeName>Search Extent</SomeName>");
sb.Append("<FilterGeometry xmlns:q1='' xsi:type='q1:EnvelopeN' xmlns=''><XMin>0</XMin><YMin>0</YMin><XMax>180</XMax><YMax>90</YMax></FilterGeometry>");

ESRI.ArcGIS.esriSystem.IXMLStream requestXmlStream =
new ESRI.ArcGIS.esriSystem.XMLStreamClass();

ESRI.ArcGIS.esriSystem.IMessage requestMessage =
new ESRI.ArcGIS.esriSystem.MessageClass();
requestMessage.ReadXML(requestXmlStream as ESRI.ArcGIS.esriSystem.IStream);

switch (requestMessage.Name)
case "MySOEAction":
ESRI.ArcGIS.esriSystem.IXMLSerializeData requestParameters = requestMessage.Parameters;
int someNameIndex = requestParameters.Find("SomeName");
string someName = requestParameters.GetString(someNameIndex);

int geometryIndex = requestParameters.Find("FilterGeometry");
ESRI.ArcGIS.Geometry.IEnvelope soapGeometry =
geometryIndex, "", "Envelope");

rex hansen said...


In general the error you specify occurs when the SOE is found, but the wsdl is not. Where did you place the SimpleSOE_CSharp.wsdl? Do you have a distributed install (SOM on one machine, multiple SOCs different machines)?

ShailGIS said...


I have got through this situation, where i saw those errors. That was because they were not placed under the right directory C:\Program Files\ArcGIS\XmlSchema.

I was able to get your solution working.

But i was also wondering, if anyone has implemented the ESRI Layout SOE (Print Map SOE) sample working through IRequestHandler.


Shail ...

Anoop Jayaram said...

Hi Sir,
Sorry for putting it here. but i have no other way to contact u..

I am a beginner level GIS Application Programmar. I had gone through
writeen by you.
very good and useful.
And now i'm trying to do the Manager Integration part with the custom tasks based on that.And I am struck with web configurator part.Not able to dynamically populate values in the task configuration in manager.
Looking for your help
Thanks in advance!

Michal said...


Is there a way to generate the wsdl from the SOE code automatically?


Research Writer said...

Many institutions limit access to their online information. Making this information available will be an asset to all.
Custom Paper Writing

Vajnorcan said...

I know this has been some time ago already, but seems like I'm bit struggling with this one.
I was able to register the extension and also the 'call SOE via SOAP' button works (so it gets the time via soe through soap), but the returnCircle method is throwing me an error, and I've noticed that after this line of code the soext object says :
m_SOH System.Runtime.Remoting.RemotingException: Remoting cannot find field 'm_SOH' on type 'SimpleSOE_CSharp.UtilSOE_CSharp'.

debugging seems to be a bit of a pain with SOE, will try out suggestions from other guys on their blogs (mapbutcher e.g.)...

any ideas what I might be doing wrong?


Sumant said...
This comment has been removed by the author.
Sumant said...

ArcGIS Server makes it easy for organizations to share mapping services and applications across the Web.

With ArcGIS Server, you can

* Connect more people with the information they need to make better decisions.
* Publish fast, intuitive Web mapping applications and services tailored to your audience.
* Simplify access to your services, data, and imagery.

Recently I just came across a good article on " Windows Server"
Here is its link.

Sumera Ishtiaq said...

hi All
i m getting same problem when i put wms request in browser
plz any one can help whats the error is?
[HttpException (0x80004005): Error HRESULT E_FAIL has been returned from a call to a COM component.]
and one thing more what is a complete url for connecting a wms layer to browser i used the following is it correct

Anonymous said...

how i can delete our comments and profile from here