ArcObjects Library Reference (Carto)

MapServer CoClass

The MapServer component provides programmatic access to the contents of a map document on disk, and creates images of the map contents based on user requests. Designed for use in building map-based web services and web applications.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Extended Error Information

Use the ISupportErrorInfo method InterfaceSupportsErrorInfo to determine if the object supports extended error information. If the object supports extended error info, VC++ developers should use the OLE/COM IErrorInfo interface to access the ErrorInfo object. Visual Basic developers should use the global error object Err to retrieve this extended error information.

Interfaces

Interfaces	Description
ILogSupport (esriSystem)	Provides access to methods for initializing an object for logging.
IMapServer	Provides access to members that serve maps.
IMapServer2	Provides access to members that serve maps.
IMapServer3	Provides access to members that serve maps.
IMapServerData	Provides access to map features and their values.
IMapServerDataAccess	Provides access to the data source behind the MapServer.
IMapServerInit	Provides access to members that support initializing a map server.
IMapServerInit2	Provides access to additional members that support initializing a map server.
IMapServerLayout	Provides access to members that serve layout components of maps.
IMapServerObjects	Provides access to core objects contained within the map document.
IMapServerObjects2	Provides access to core objects contained within the map document.
IMapServerObjects3	Provides access to core objects contained within the map document.
IObjectActivate (esriSystem)	Provides access to methods for activating and deactivating objects.
IObjectConstruct (esriSystem)	Provides access to methods for constructing an object.
IObjectUpdate (esriSystem)	Provides access to methods for updating an object.
IObjectValidate (esriSystem)	Provides access to methods for validating an object.
IRequestHandler (esriSystem)	Provides access to members that control handing of request messages.
IRequestHandler2 (esriSystem)	Provides access to members that control handing of request messages.
IRESTRequestHandler (esriSystem)	Provides access to REST request for SO or SOE.
IServerObject (esriServer)	Provides access to properties of a map or geocode server object.
IServerObjectConfigurationManager (esriServer)	Provides access to additional members that support initializing a server object.
IServerObjectConfigurationManager2 (esriServer)	Provides access to additional members that support initializing a server object.
IServerObjectExtensionManager (esriServer)	Provides access to members that help locate installed server object extensions.
ISupportErrorInfo	Indicates whether a specific interface can return Automation error objects.
ITiledMapServer2	Provides access to members that serve tiled maps.
ITiledMapServer3	Provides access to members that serve tiled maps.

Remarks

MapServer is a coarse-grained ArcObject. This object allows users to display and query ArcGIS map documents in internet development environments. In a server environment, MapServer objects can be accessed via SOAP/XML over an HTTP connection (Internet) or via COM in a Server Object Extension (SOE). In SOE, you can use IRESTRequestHandler to process REST/JSON request. The MapServer coclass contains several interfaces like IMapServer, IMapServerDataAccess with functions for displaying and querying a map service.

In addition to MapServer, a number of MapServer objects are defined to represent input and output parameters for methods on MapServer interfaces. For example, the IMapServer method ExportMapImage requires two inputs: a description of the map to be exported and a description of the output parameters. These inputs are captured in the MapDescription and ImageDescription objects.

Though the methods and properties available through MapServer and its associated objects offer important mapping functionality, they cannot possibly encapsulate all that ArcObjects offers. In some cases you may want to use other, finer-grained, ArcObjects in conjunction with MapServer. Starting at 10.1, you can only do this in an SOE using the IMapServerDataAccess interface which will give you access to the datasource (IFeatureClass or ITable ) of a layer or stand-alone table.

Please note that accessing fine-grained ArcObjects through IMapServerObjects interface has been deprecated at 10.1. Typically you would want to use IMapServerObjects interface to make changes to map, such as modifying a layer's renderer or adding a new layer. Starting at 10.1, you do not need to access fine-grained ArcObjects since these capabilities are available via the coarse-grained MapServer's API. If the mapservice you are accessing is enabled with dynamicLayers (SupportsDynamicLayers), you can use IDynamicLayerDescription to change renderer or to set datasource for a new layer.

It is important to know that all changes made to the MapServer object are temporary. A temporary change would include changes to the MapDescription or LayerDescription using IMapDescription, ILayerDescription or IDynamicLayerDescription. For example, you might change the geographic extent of a map (MapArea), change the visibility (Visible) or renderer (DrawingDescription) of a layer or even add a new layer on-the-fly. These changes are temporary and valid for the duration of the call (stateless). Once the call has ended the MapServer object returns to it's default state and does not remember the changes made by the previouscall.

You may find GenerateDataClasses function to get unique values from fields or generate classes from a field and optionally ask for renderer that can be used with ExportMapImage.

Only certain symbols are supported when working with the MapServer WSDL. These include ISimpleMarkerSymbol, ICharacterMarker, IPictureMarker, ISimpleLineSymbol, ISimpleFillSymbol and IPictureFill.

A MapServer service can have an associated tiled map cache. ArcGIS map services can use a tile cache to significantly improve performance while delivering maps. A map service that fulfills requests with pre-created tiles from a cache instead of dynamically rendering part of the map is called a cached map service. The map cache is a repository that contains image tiles for map extents at specific scale levels.

Service publishers create the cache for a map service using geoprocessing tools in ArcCatalog or via scripting. Applications that work with a cached map service can directly access tiles from the tile cache. Such applications include ArcGIS for Desktop, the ArcGIS for Server Web ADF applications. While other applications that are based on ArcGIS for Server JavaScript, Silverlight or Flex API access tiles using the tile handler.

For optimal performance, use caches. Applications built with caches do not use the parent map service, but instead pull the images directly from the cached virtual directory or by using a tile handler web service running on the server. Use ICacheDescription to get information on the cached service.

Working with MapServer with a cached map service can be different than working with a map service without a cache. Though you will be able to query against a cached map service just as you would a non-cached map service, you will see differences when working with cached map service's MapDescription and the LayerDescription of any map layer belonging to a cache.

If the map service is a cached map service then custom graphics, the rendering of selected features etc. cannot be applied to the MapDescription. In addition, any changes made to the LayerDescription of any of the map layers, such as applying a definition expression, applying a selection buffer, toggling the visibility of labels or changing the visibility of the layer itself are ignored. You will need to use ITileCacheInfo to change the spatial reference or call ExportMapImage function with different spatial reference set to IMapDescription. In the latter case you will get one single image projected to the requested spatial reference instead of multiple tiles.