The ArcGIS Server SOAP API is an XML-structured language for communicating with
ArcGIS Server services based on the SOAP standard. Server objects and some
server object extensions have a defined set of SOAP elements and attibutes,
known as a schema, they can utilize to process SOAP requests and
generate SOAP responses. Since this capability is enabled at the server object
level, as a developer you can interact with a server object using SOAP without
using a Web service. ArcGIS Server Web services expose this capability via a
Web service endpoint, but the SOAP request and response are still handled by
the server object or server object extension directly. The easiest way to work
with the SOAP API is to use a SOAP toolkit to generate SOAP proxies and value
objects in the native development environment. Instead of managing SOAP strings
directly, you can use the native proxy and value objects to work with ArcGIS
Server services via a Web service endpoint or via the SOM.
The SOAP API is designed to make stateless use of ArcGIS Server services.
As a result, methods on the stateless ArcObjects interfaces implemented
by a server object or extension mirror the methods on a SOAP
proxy. For example, both the MapServer SOAP proxy and the
IMapServer ArcObjects COM interface expose the ExportMapImage
method. While the protocol and types are different, the
usage is generally the same. A call to the ExportMapImage method
generates a new map image without inherently storing or changing the state
of the map server object. A list of the complimentary SOAP proxy and
ArcObjects COM interfaces are provided in the ArcGIS Server Web Services
Implementation section below.
ArcGIS Server Connections
ArcGIS Server services can be made accessible via Local and
Internet connections. Local connections are established by using
ArcObjects within a client application to connect to the Server Object
Manager (SOM). Internet connections are established by using native
objects within a client application to connect to a Web service
endpoint. "Native object" means an object managed solely in the
native development environment, like .NET or Java. Local
connections offer the ability to work with services, namely server
objects and server context, using the ArcObjects API and the SOAP
API. Stateful changes to a service (server object)
can only be made using the ArcObjects API and thus require a local
connection. Internet connections only offer the ability to work with
services using the SOAP API, so all service interaction is
stateless. In general, ArcGIS Server connections in
client applications can be summarized as follows:
Internet connections always use the SOAP API and define a connection using a
url to a Web service endpoint. Internet connections can be
used by both internal (LAN) and external (Internet) clients.
Local connections always use the ArcObjects API and may use
the SOAP API, depending on the client application. Connections
are defined using the name of the SOM machine with optional identity
credentials. Local connections can only be used by internal
Both connection types can be used to consume ArcGIS Server serivce
in pre-created, rich application clients such as ArcMap, ArcCatalog,
and ArcGIS Explorer. The Web ADF and ArcGIS Server Manager
also enable the use of ArcGIS Server services without explicitly defining which
API you're using. The API becomes important for
application developers to determine the capabilities and limits when
working with ArcGIS Server services. As a result, working with the
SOAP API will require developer level skill and knowledge for a number of Web
service standards and specifications, in addition to ArcGIS Server service
Web Service Standards
The ArcGIS Server SOAP API rests on two standard XML-based specifications:
- Web Service Description Language and
- Simple Object Access Protocol. WSDL is a
specification used to describe networked XML-based services.
Although the term "Web Service" is part of the moniker, WSDL is not restricted
to traditional HTTP-based Web services. In general, WSDL provides a
simple way for service providers to describe the basic format of
requests to their services, regardless of the underlying
protocol. One of those protocols, and by far the most popular, is
SOAP. SOAP is used to describe the format of a message sent to
a networked service. SOAP messages can be transmitted to
a service via a number of transport protocols, including HTTP
and DCOM (distributed COM).
ArcGIS Server SOAP Implementation
SOAP support for server objects and server object extensions is defined at the
ArcObjects level. So at some point in the communication cycle, ArcObjects
must be used. Two basic ArcObjects interfaces are used to interact with
the SOAP API: IServiceCatalogAdmin and IRequestHandler. Updated
versions of both interfaces are available, for example
IServiceCatalogAdmin2 and IRequestHandler2. IServiceCatalogAdmin is
used to get a WSDL for server objects, server object extensions and
ServiceCatalog. ServiceCatalog is a well-known service managed
internally by the SOM and used to get a list of services and
their properties from an ArcGIS Server site using the SOAP API.
IRequestHandler is used to process SOAP requests and generate SOAP
responses. Interaction with an ArcGIS Server service via the
SOAP API rests on the implementation and use of the IRequestHandler
interface. The following ArcGIS Server services and
extensions provide a WSDL and implement the IRequestHandler
interface, thus they can be utilized via the SOAP API:
ArcObjects Server Object or Extension Type|
The Server Object Manager (SOM) is responsible for providing the WSDL for a
service type to a client. The WSDL for each supported service type is
stored in the <ArcGIS Install>\XMLSchema folder using the server type
name with the file extension ".wsdl". The content for each WSDL is
provided via the links below:
Using the ArcObjects API and the IServiceCatalogAdmin interface on the
ServiceCatalog object, you can get access to the WSDL for each service
type. The ServiceCatalog (Catalog) WSDL is returned by the
GetCatalogDescriptionDocument() method and each service type (e.g.
MapServer, GeocodeServer) WSDL is returned by the GetDescriptionDocument()
method. The byte array returned from either method
contains the WSDL document referenced by the links above. The
IServiceCatalogAdmin interface is included in the ESRI.ArcGIS.Server.dll.
ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection gisconnection =
gisconnection.Host = servername;
IServerObjectManager serverManager = gisconnection.ServerObjectManager;
IServerContext serverContext = serverManager.CreateServerContext(servicename, servertype);
IServiceCatalogAdmin2 isc = (IServiceCatalogAdmin2)serverContext.CreateObject("esriServer.ServiceCatalog");
UTF8Encoding utf8 = new UTF8Encoding();
// Catalog WSDL
byte bitscatalog = isc.GetCatalogDescriptionDocument("Catalog", "http://localhost");
string catalog_wsdl = utf8.GetString(bitscatalog);
// Service WSDL
byte bitsservice = isc.GetDescriptionDocument(servicename, servertype, "http://localhost");
string service_wsdl = utf8.GetString(bitsservice);
SOAP Requests and Responses
All SOAP requests to ArcGIS Server services are handled by the server object
via the implementation of the IRequestHandler interface. As a result,
using the ArcObjects API a client to ArcGIS Server can use the IRequestHandler
interface to submit a SOAP request and return a SOAP response. The
IRequestHandler interface defines the HandleStringRequest method to process
SOAP string requests and generate SOAP string responses. The following
code example illustrates how to query interface to the IRequestHandler
interface from a MapServer object, create the SOAP string request to get
the default map name, and submit the request with a capability
list to return a SOAP string response. The
IRequestHandler interface is included in the ESRI.ArcGIS.System.dll and
referenced via the ESRI.ArcGIS.esriSystem namespace.
IRequestHandler irh = (IRequestHandler)serverContext.ServerObject;
string soap_request = "<?xml version='1.0' encoding='utf-8' ?>";
soap_request += "<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:tns='http://www.esri.com/schemas/ArcGIS/9.2'>";
soap_request += "<soap:Body>";
soap_request += "<tns:GetDefaultMapName>";
soap_request += "</tns:GetDefaultMapName>";
soap_request += "</soap:Body>";
soap_request += "</soap:Envelope>";
string soap_response = irh.HandleStringRequest("map,query,data", soap_request);
Creating and parsing SOAP strings can be a labor intensive process.
Using the raw WSDL to determine how to create SOAP request and process SOAP
responses can be a daunting task. As a result, ESRI
has leveraged existing technology standards coupled with developer
environment utilities to make this process easier. The following sections
illustrate the technologies and utilities provided.
Consuming SOAP Services
Developer environments, such as .NET or Java, provide SOAP toolkits
to generate local, native objects as value objects and a proxy
class. The WSDL provides the client what it needs to generate the proxy
and value objects, thus no proprietary components related to the Web service
Value objects are simply objects that store values or properties.
Depending on the WSDL, there can be many different types of value
objects. On the other hand, there is only one proxy class per SOAP
service type. The proxy has both 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 to be used by the
client. So working with a rich client object environment makes
it much 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.
Consuming ArcGIS Server services using the SOAP API
ArcGIS Server developers who want to use the SOAP API to work with ArcGIS
Server services have two options to consider, depending on the connection
type and client components available.
If the Web 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, two proxies are provided: a Web service proxy and a DCOM proxy.
The Web service proxy works with ArcGIS Server Web services
using SOAP over HTTP and requires a url endpoint. The DCOM
proxy uses SOAP over DCOM to work with server objects via the
IRequestHandler interface. It requires an ArcGIS Server Local
connection and access to server context. In either case, the value
objects utilized by the proxies are shared in the same library and same
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. Note: the sample code provided
for each server or extension type in this section illustrates 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 SDK to generate Web service proxies and value objects from ArcGIS
Server Web service endpoints. Without ArcObjects COM proxies on the
client, no remote COM object management can occur - thus using SOAP over
DCOM is not available. Note, no ESRI products are required on the
client for this option.
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 will focus on ArcGIS Server Web services
implementation and consumption.
ArcGIS Server Web Services Implementation
In ArcGIS Server for Microsoft .NET, ArcGIS Server Web services are
deployed as a compiled ASP.NET Web application which 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 so you don't have to. This means ArcObjects
COM proxies do not need to be on the client. In fact, no ESRI software is
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 (e.g. .NET, Java, Perl, etc.) will
determine 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 that 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 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 use the following url pattern:
http://<Web Server Hostname>/<ArcGIS
<Web Server Hostname>
is the hostname of the Web server on
which the ArcGIS Server Web services application is deployed.
is the name of the virtual directory in
which the "services
" are made available. Each instance
is associated with one SOM. The instance name entered during
the ArcGIS Server post-install or using the AddInstance.exe utility.
is the name of the ArcGIS Server service.
is the server object or server object extension
type. This type must provide and WSDL and implement IRequestHandler
to be utilized via SOAP.
The WSDL for a server object or extension will provide 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. Recall that the SOAP API is designed
to work with ArcGIS Server services in a stateless manner, thus 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. As a result, SOAP value objects and ArcObjects types used
by the stateless interfaces will 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 GIS Server. For example, the MapServer SOAP proxy
and IMapServer ArcObjects interface both share the method
ExportMapImage. 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
thus require connection libraries and ArcObjects COM proxies on the
client. Both 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, no ESRI components need to be installed or
available on the client. Thus a client application can utilize
ArcGIS Server Web services using the SOAP API much like any other
SOAP-based Web service.
The table below provides 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
Dynamically generated Web service proxy classes share the same
functionality except 1) the proxy class name will be <service
name>_<server type> and 2) the namespace for the proxy and value
objects is user defined. The value object class names and
properties are the same.
ArcObjects server type
SOAP API proxy class
ArcObjects API stateless interfaces|
The code samples below illustrate SOAP proxy class initialization with an
ArcGIS Server map service:
Web ADF - Web service proxy
string endpoint = "http://MyWebServer/arcgis/services/MyMapServiceName/MapServer";
ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy mapserver =
Web ADF - DCOM proxy (also requires connection libraries ESRI.ArcGIS.ADF.dll
ESRI.ArcGIS.ADF.Identity id = new ESRI.ArcGIS.ADF.Identity(username, password, domain);
ESRI.ArcGIS.ADF.ArcGISServer.MapServerDcomProxy mapserver_dcom =
(MapServerDcomProxy) MapServerDcomProxy.Create(SOMname, servicename, id);
// do something with the DCOM proxy
Dynamic - Web service proxy
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 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: geocode services, geoprocessing services, etc. Code samples
are provided in the SOAP API discussion sections for each server
type illustrating how to define which ArcGIS Server Web service will
be used by a SOAP proxy.
Walkthrough: Create an ArcGIS Server SOAP proxy and value objects dynamically
using Visual Studio 2005.
In this walkthrough, we will create a desktop client application in
Microsoft Visual Studio 2005 to consume an ArcGIS Server Web map
service. The MapServer proxy and value objects for the map
service will be created dynamically in Visual Studio 2005 using the SOAP
Toolkit (wsdl.exe) included with the .NET 2.0 SDK. The application
will use the ArcGIS Server SOAP API via the MapServer proxy and value
objects to request a new map image and display it in the desktop
client application. An ArcGIS Server map service that is
enabled as a Web service will be required for this walkthrough.
Create the Windows Application project
Add a reference to an ArcGIS Server Web map service
In Visual Studio 2005, click File, New Project.
In the Add New Project dialog, under Project Types, click Visual C# Projects.
Under Templates, select Windows Application. For the project name, specify
Click OK. The project will open with a form named Form1.
Add controls the Windows form
In Solution Explorer under the SOAPClient project, right-click the References
folder and select Add Web Reference.
In the Add Web Reference dialog, in the URL combo box, enter the Web
service endpoint to the WSDL for an ArcGIS Server Web map service. For
Note that "?wsdl" as appended to specify that the WSDL for the map service
should be returned. The methods on the MapServer SOAP proxy should
be displayed. Change the Web Reference name to something intuitive,
such as "wsmap", and click Add Reference. The MapServer proxy and value
objects are created for you. Note that the Web reference name is the
namespace for the MapServer proxy and value objects.
Add code to get a map image and display in the PictureBox control
Add a Button control to the form and set it's Text property to "Get Map".
Add a PictureBox control to the form. Organize the controls on the
form using the screenshot below.
Run the application
Double-click on the Get Map button to open the Form1.cs code file to the
OnClick event. The following code will use the dynamic ArcGIS Server Web
service proxy and value objects to request a map image from an ArcGIS Server
In the OnClick event method, add the following code:
Create a new instance of the MapServer proxy and set the Url property to a
valid ArcGIS Server Web map service endpoint.
wsmap.NorthAmerica_MapServer mapserver = new wsmap.NorthAmerica_MapServer();
mapserver.Url = "http://localhost/arcgis/services/NorthAmerica/MapServer";
To create a map image two value objects are required, a MapDescription and an
ImageDescription. The MapDescription provides the information on the
content of the map and the ImageDescription provides image
properties. For the MapDescription, we'll use the default
MapDescription of the default map data frame in the map document associated
with the map service.
wsmap.MapServerInfo mapinfo = mapserver.GetServerInfo(mapserver.GetDefaultMapName());
wsmap.MapDescription mapdesc = mapinfo.DefaultMapDescription;
The ImageType value object stores the image format and how it will be returned
to the client. In this case, a jpeg image will be created and the url to
the image on a Web server will be returned to the client.
wsmap.ImageType imgtype = new wsmap.ImageType();
imgtype.ImageFormat = wsmap.esriImageFormat.esriImageJPG;
imgtype.ImageReturnType = wsmap.esriImageReturnType.esriImageReturnURL;
The ImageDisplay value object stores the size and resolution of the map
image. The size is defined in pixels - in this case the size of the
PictureBox control. The image DPI is used by the map server object to
calculate map scale. It will be used to determine if scale
dependent layers should be drawn and the size or width
of feature or graphic symbols.
wsmap.ImageDisplay imgdisp = new wsmap.ImageDisplay();
imgdisp.ImageHeight = pictureBox1.Height;
imgdisp.ImageWidth = pictureBox1.Width;
imgdisp.ImageDPI = 96;
ImageDescription is a value object that stores a reference to the ImageDisplay
and ImageType value objects.
wsmap.ImageDescription imgdesc = new wsmap.ImageDescription();
imgdesc.ImageDisplay = imgdisp;
imgdesc.ImageType = imgtype;
The ExportMapImage method on the MapServer proxy serializes the MapDescription
and ImageDescription value objects into a SOAP request for a new map image
and submits it to the Web service endpoint defined earlier. A
SOAP response is returned and the MapServer proxy deserializes the contents and
returns a MapImage value object. In this case, MapImage
has a property, ImageURL, which stores the url to the map image generated
by the ArcGIS Server map service.
wsmap.MapImage mapimg = mapserver.ExportMapImage(mapdesc, imgdesc);
Using standard .NET network classes to manage HTTP requests and responses, the
map image can be retrieved as a byte stream from the map image url. A new
native .NET Image is created locally in memory and assigned to
the PictureBox control Image property for display.
System.Net.HttpWebRequest webreq =
System.Net.HttpWebResponse webresp =
System.Drawing.Image img = System.Drawing.Image.FromStream(webresp.GetResponseStream());
pictureBox1.Image = img;
Start the application and click on the Get Map button. The PictureBox
control should display the map image generated by ArcGIS