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.
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 either desktop, LAN/WAN, or internet development environments. In the desktop environment you can use MapServer, as well as other coarse-grained objects as a "short-cut" for ArcObjects development.  Operations that took many lines of code may now just take a few. In a server environment, MapServer objects can be accessed via Distributed COM (DCOM) over a TCP/IP connection (Intranet) or via SOAP/XML over an HTTP connection (Internet).

The MapServer coclass contains several interfaces with basic functions for displaying (IMapServer and IMapServerLayout) and querying (IMapServer and IMapServerData) an ArcGIS map document (.msd, .mxd or .pmf).

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 many cases you may want to use other, finer-grained, ArcObjects in conjunction with MapServer. You can do this using the IMapServerObjects interface. Through this interface you can access ILayer, IMap and IPageLayout. For example, you can make changes to the map, such as adding a new layer, using IMap.

It is very important to distinguish between temporary and permanent changes to the MapServer object. A temporary change would include changes to the MapDescription or LayerDescription using IMapDescription and ILayerDescription. For example, you might change the geographic extent of a map (MapArea) or change the visibility of a layer (Visible). These changes can be temporary and valid for the duration of the call. Once the call has ended the MapServer object returns to it's default state.

Permanent changes to the MapServer object can be done in two ways.  The first is by changing MapServer properties using such interfaces as IMapDescription and ILayerDescription and then calling the IMapServerObjects method ApplyMapDescription. This will update the state of the fine-grained ArcObjects. Another way to change the MapServer object is to access the underlaying fine-grained ArcObjects directly using the methods on IMapServerObjects, make a change such as adding a new layer or changing a layer's rendering, and then calling RefreshServerObjects. This refreshes the MapServer object with the current state held by the fine-grained ArcObjects.

You should use non-pooled objects when permently changing the state of fine-grained ArcObjects.

Please note that optimized MapServer based on msd does not allow access to the fine grained objects and only works in stateless manner. You cannot make permanent change requests to an optimized MapServer object, all changes are temporary and valid only for the duration of the call.

Only certain symbols are supported when working with the MapServer WSDL or accessing a MapServer object through an AGSServerConnection (LAN or internet). These include ISimpleMarkerSymbol, ICharacterMarker, IPictureMarker, ISimpleLineSymbolISimpleFillSymbol and IPictureFill. ESRI recommends against the use of SimpleFillSymbols with a Style other than esriSFSSolid.  Usage of other Style options may produce unexpected results in a standard map service.  The optimized MapServer does not support usage of Styles other than esriSFSSolid - use other fill symbol types such as ILineSymbol instead.

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 directory that contains image tiles for map extents at specific scale levels.

Applications that work with a cached map service can directly access tiles from the tile cache. Such applications include ArcGIS Desktop, the ArcGIS Server Web ADF Applications and ArcGIS Javascript applications.

Service publishers create the cache for a map service using geoprocessing tools in ArcCatalog or via scripting.

There are two types of caches. A map service can have either a single fused cache or a multi-layer cache. A single fused cache contains image tiles that are created by fusing all the layers in a map document into a single image representing the tile. A multi-layer cache contains individual layer caches each of which contains image tiles that are created by rendering a specific layer in the map document. Please note that an optimized MapServer service does not support multi-layer cache.

Clients behave differently with these two cache types. All client applications have the ability to fetch and use tiles from a map service with a fused map cache. In ArcMap, fused caches appear as group layers with feature selection disabled, label selection that cannot be adjusted, and visibility that cannot be controlled by turning sub-layers ON and OFF.

Only the ArcGIS Desktop client has the ability to fetch and use (fuse) tiles from a service that has a multi layer cache. All other clients treat a service with a multi layer cache as though it were not cached they delegate the job of generating map images to the service which does make use of the tiles in the individual layer caches. Multi-layer caches appear in a client as collections of layers with controllable visibility, labeling, and feature selection enabled.  

For optimal performance, use fused caches. Applications built with fused caches do not use the parent map service, but instead pull the images directly from the cachevirtual 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 and 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 has a fused cache custom graphics, including the rendering of selected features, 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. When the map service has a Multi-layer cache changes to the MapDescription are honored. You will be able to render custom graphics and selection features, including features belonging to cached layers. However, you will not be able to apply a definition expression to or toggle the value of the ScaleSymbol property of individual layers that are cached. These will be ignored. Finally, applying a new spatial reference on cached map services though IMapDescription will not work. The cached layers will not draw. You will need to use ITileCacheInfo to change the spatial reference.