Consuming SOAP services

Local (DCOM) connections are only supported for ArcGIS Server versions prior to 10.1.

About consuming SOAP services

Developer environments, such as .NET or Java, provide Simple Object Access Protocol (SOAP) toolkits to generate local, native objects as value objects and a proxy class. The Web Service Description Language (WSDL) provides the client what it needs to generate the proxy and value objects; therefore, no proprietary components related to the Web service are necessary. See the following illustration of the SOAP toolkit:

Value objects are objects that store values or properties. Depending on the WSDL, there can be many different types of value objects. Alternatively, there is only one proxy class per SOAP service type (the proxy has properties and methods). The methods are designed to create and submit a SOAP request and return a SOAP response. The proxy uses the value objects to construct (serialize) a SOAP request.

The proxy also deserializes the SOAP response and constructs value objects used by the client. Working with a client object environment makes it easier to consume and utilize a SOAP service because you are using native objects to store properties (value objects), and manage SOAP requests and responses (proxy) on the client. See the following illustration:

Illustration showing the client and server application.

Consuming ArcGIS Server services using the SOAP API

ArcGIS for Server developers who want to use the SOAP application programming interface (API) to work with ArcGIS Server services have the following options to consider, depending on the connection type and client components available:

If the Web Application Developer Framework (ADF) is available, use the pre-generated ArcGIS Server SOAP proxies and value objects included with the Web ADF in ESRI.ArcGIS.ADF.ArcGISServer. For each server type that supports SOAP, the Web service proxy and Distributed Component Object Model (DCOM) proxy are provided. The Web service proxy works with ArcGIS Server Web services using SOAP over Hypertext Transfer Protocol (HTTP) and requires a uniform resource locator (URL) endpoint. The DCOM proxy uses SOAP over DCOM to work with server objects via the IRequestHandler interface. DCOM requires an ArcGIS Server local connection and access to server context. In either case, value objects utilized by the proxies are shared in the same library and namespace. Shared means that if multiple server types define the same value object (in the WSDL), only one value object is generated and "shared" for all proxies. The code examples provided for each server or extension type in this topic show the use of the Web service proxy included with the Web ADF.
If the Web ADF is not available, use the SOAP toolkit included with the .NET software development kit (SDK) to generate Web service proxies and value objects from ArcGIS Server Web service endpoints. Without ArcObjects Component Object Model (COM) proxies on the client, no remote COM object management can occur; therefore, using SOAP over DCOM is not available. ESRI products are not required on the client for this option. See the following illustration:

In most cases, the ArcGIS Server SOAP API will be utilized when working with an ArcGIS Server Web service. As a result, the remaining sections in this topic focus on ArcGIS Server Web services implementation and consumption.

ArcGIS Server Web services implementation

In ArcGIS for Server for Microsoft .NET, ArcGIS Server Web services are deployed as a compiled ASP.NET Web application that contains an HTTP handler. The HTTP handler uses IServiceCatalogAdmin and IRequestHandler internally to expose the SOAP API over HTTP.

The ArcGIS Server Web service application manages all interaction with the SOAP API via ArcObjects, which means ArcObjects COM proxies do not need to be on the client. ESRI software is not required on the client to consume ArcGIS Server Web services. Only the ability to submit and receive SOAP strings over HTTP is required.

The development environment (for example, .NET, Java, Perl, and so on) determines how this capability is implemented, but in the end, the ArcGIS Server Web service must receive a SOAP request and return a SOAP response. This also means the deployment environment of an ArcGIS Server Web service does not dictate which development environments can consume it.

An ArcGIS Server Web service can be exposed as a .NET Web service on Internet Information Services (IIS) and be consumed by a Java application because the communication protocol is based on common standards (SOAP and HTTP).

Consuming ArcGIS Server Web services

ArcGIS Server Web services URL syntax is http://<Web Server Hostname>/<ArcGIS Instance>/services/<ServiceName>/<ServiceType>.

The following describes each component in the URL syntax:

Web Server Hostname—Hostname of the Web server on which the ArcGIS Server Web services application is deployed.
ArcGIS Instance—Name of the virtual directory in which the "services" are made available. Each instance is associated with one server object manager (SOM); the instance name entered during the ArcGIS for Server post-install or using the AddInstance.exe utility.
ServiceName—Name of the ArcGIS Server service.
ServiceType—Server object or server object extension type. ArcGIS for Server includes a set of standard service types (for example, MapServer, GeocodeServer, and so on). The type must provide a WSDL and implement IRequestHandler to be utilized via SOAP. Server types are defined using a CamelCase pattern.

The WSDL for a server object or extension provides the necessary information to determine how to interact, via SOAP, with the Web service. The WSDL for a server object or extension type can be returned by adding "?wsdl" to the URL.

ArcGIS Server proxies and value objects

The proxy classes and value objects for each ArcGIS Server service type are generated using the service specific WSDL. There is one proxy class for each service type. The capabilities of an ArcGIS Server service using the SOAP API are defined by the methods of the SOAP proxy. The SOAP API is designed to work with ArcGIS Server services in a stateless manner; therefore, the proxy class provides methods to initiate stateless requests to an ArcGIS Server service and return results.

The capabilities of the SOAP proxy mirror the stateless ArcObjects interfaces implemented by the server object. For example, the MapServer SOAP proxy shares the same methods as the stateless ArcObjects interfaces implemented by the ArcObjects MapServer object (IMapServer and ITiledMapServer).

The ArcGIS Server SOAP proxy uses value objects when calling a method and returning results. SOAP value objects and ArcObjects types used by the stateless interfaces share a common naming scheme, but are different object types. The value objects are native .NET objects while the server object interfaces reference COM objects on the geographic information system (GIS) server. For example, the MapServer SOAP proxy and IMapServer ArcObjects interface share the ExportMapImage method. However, the SOAP proxy takes two input parameters, native .NET objects of type MapDescription and ImageDescription. The IMapServer ArcObjects interface takes two input parameters—interface references to COM objects available on the GIS server of type IMapDescription and IImageDescription. The MapServer proxy returns a native .NET MapImage value object, while IMapServer returns an IMapImage reference to a COM object on the GIS server.

The Web ADF includes SOAP proxy classes to use the SOAP API via Internet (Web service) or local (DCOM) connections. Microsoft .NET provides a SOAP toolkit (wsdl.exe) to generate the proxy classes and value objects. The SOAP proxies and value objects included with the Web ADF were built using the .NET SOAP toolkit—they were designed to work solely with ArcGIS Server Web services. The DCOM proxies extend the SOAP proxies to work with local connections to ArcGIS Server and require connection libraries and ArcObjects COM proxies on the client. SOAP and DCOM proxies share the same set of value objects.

The .NET SOAP toolkit can also be used to generate SOAP proxies and value objects dynamically. ESRI components do not need to be installed or available on the client. A client application can utilize ArcGIS Server Web services using the SOAP API like other SOAP-based Web services.

The following table shows the SOAP API proxy class names for the ArcGIS Server service types and their complimentary stateless interfaces in the ArcObjects API. The SOAP API proxy classes in the Web ADF are contained in the ESRI.ArcGIS.ADF.ArcGISServer.dll assembly. Dynamically generated Web service proxy classes share the same functionality except for the following:

Proxy class names will be <service name>_<server type>
Namespaces for the proxy and value objects are user defined. The value object class names and properties are the same.

ArcObjects server type	SOAP API proxy class			ArcObjects API stateless interfaces
	Web ADF		Dynamic
	Web service	DCOM	Web service
MapServer	MapServerProxy	MapServerDcomProxy	<ServiceName>_MapServer	IMapServer, ITiledMapServer
GeocodeServer	GeocodeServerProxy	GeocodeServerDcomProxy	<ServiceName>_GeocodeServer	IGeocodeServer
GPServer	GPServerProxy	GPServerDcomProxy	<ServiceName>_GPServer	IGPServer
GeoDataServer	GeoDataProxy	GeoDataDcomProxy	<ServiceName>_GeoDataServer	IGeoDataServer
GlobeServer	GlobeServerProxy	GlobeServerDcomProxy	<ServiceName>_GlobeServer	IGlobeServer
NAServer	NAServerProxy	NAServerDcomProxy	<ServiceName>_NAServer	INAServer

The following code examples show SOAP proxy class initialization with an ArcGIS Server map service.

The following code example shows the Web ADF Web proxy:

[C#]


        string endpoint = "http://MyWebServer/arcgis/services/MyMapServiceName/MapServer";
ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy mapserver = new
    ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy(endpoint);

-or-

[C#]


        ESRI.ArcGIS.ADF.Identity id = new ESRI.ArcGIS.ADF.Identity(username, password,
    domain);
ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy mapserver =
    ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy.Create(
    "http://MyWebServer/arcgis/services", "MyMapServiceName", id);

The following code example shows the Web ADF DCOM proxy (also requires connection libraries ESRI.ArcGIS.ADF.dll and ESRI.ArcGIS.ADF.Connection.dll):

[C#]


        ESRI.ArcGIS.ADF.Identity id = new ESRI.ArcGIS.ADF.Identity(username, password,
    domain);
ESRI.ArcGIS.ADF.ArcGISServer.MapServerDcomProxy mapserver_dcom = (MapServerDcomProxy)
    ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy.Create("MySOMServerName", 
    "MyMapServiceName", id);
// Do something with the DCOM proxy.
mapserver_dcom.Dispose();

The following code example shows the dynamic Web service proxy:

[C#]


        wsmap.AMapServiceName_MapServer mapserver = new wsmap.AMapServiceName_MapServer();
mapserver.Url = "http://MyWebServer/arcgis/services/MyMapServiceName/MapServer";

The proxy and value objects for an ArcGIS Server service only need to be generated once per service type. Once the Web service proxy and value objects for an ArcGIS Server service have been created, they can be reused with other ArcGIS Server Web services of the same type, even though the proxy class name contains the original service name (dynamic proxies only). For example, if a Web service proxy class is generated dynamically using a map service named NorthAmerica, the proxy class name will be NorthAmerica_MapServer. The default endpoint for the MapServer proxy will be associated with the NorthAmerica map service.

To use another ArcGIS Server Web map service named Europe, set the URL property to define the Web service endpoint to the Europe ArcGIS Server Web map service. To change the service for the Web ADF MapServer proxy classes (which are pre-generated), the proxy constructor requires a URL input parameter to define the Web service endpoint for the ArcGIS Server Web map service you want to use. The same applies for all ArcGIS Server types, for example, geocode services, geoprocessing services, and so on.

Code examples are provided in the SOAP API sections for each server type that show how to define the ArcGIS Server Web service used by a SOAP proxy.

Asynchronous methods

The client-side asynchronous capabilities of a Web service are defined by the underlying development environment, in this case, .NET. The WSDL toolkit (wsdl.exe) included with the .NET SDK generates the Begin\End and Async\Completed asynchronous methods. Both methods are valid and supported in .NET 2.0, 3.0, and 3.5. Using Add Web Reference within Visual Studio 2005 only generates the Async\Completed methods. To construct both, use wsdl.exe on the command line.

The Begin\End pattern has existed since .NET 1.1 and uses a callback technique to manage and track an asynchronous call. The Async\Completed pattern was introduced in .NET 2.0 as an event-driven asynchronous model. Both techniques initiate a call to the remote Web service on a threadpool thread. The asynchronous response to the callback method for the Begin\End pattern is handled in a threadpool thread. The difference is how the response is handled.

The response handled by Begin's callback method executes on a threadpool thread and is provided with an IAsyncResult type. In the callback method, explicitly call the End method and provide the IAsyncResult type (you must have a reference to the original proxy type on which to call the method).

The Completed handler executes on the main thread; therefore, managing user interface (UI) updates to a Windows form with results from an asynchronous Web service call does not require that the developer manage cross thread interaction. The event to a Completed handler contains an IAsyncResult and the object returned from the method call (you do not need a reference to the original proxy type).

Both patterns include access to IAsyncResult, which maintains an IsCompleted property and can be used to check the status of the asynchronous request. In many cases, the event-driven model can be easier to implement.

Both patterns are illustrated via a set of button click events in a Windows form and a separate custom IAsyncResult class. These methods were designed for use in desktop clients, but can be used in a Web application. In that case, explicitly manage synchronicity between the client Web and Web service.

The DCOM proxies included with the Web ADF (ESRI.ArcGIS.ADF.ArcGISServer) do not support asynchronous methods. Only Web service (HTTP) proxies are supported.

Consuming SOAP services

About consuming SOAP services

Consuming ArcGIS Server services using the SOAP API

ArcGIS Server Web services implementation

Consuming ArcGIS Server Web services

ArcGIS Server proxies and value objects

Asynchronous methods

See Also: