Map services

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

Map overview

The majority of geographic information system (GIS) applications are based on one or more maps, whether the map is the result or output of an application, or the central aspect of the application with which users interact. ArcGIS for Server applications are no different.

A map is a collection of layers of geographic information and graphic elements with a coordinate system and an extent. A layer is a thematic representation of geographic information that is stored in a database.

ArcGIS maps are stored in map documents (.mxd) or map service definitions (.msd) that are created using the ArcMap desktop application. In a map document, a map is referenced by a data frame. Map documents have one or more data frames and contain a single map layout that includes its data frames and marginalia. Map service definitions are derived from map documents and provide access to optimized drawing capabilities of ArcGIS for Server, but are limited in their functionality.

You can interact with maps, layouts, and layers in a variety of ways including the following:

Pan and zoom interactively
Turn layer visibility on and off
Identify features
Find features
Select features by their attributes or their geometry
Output maps to printers or as images

Maps are also windows into a geographic database and are used to define the inputs for various analysis functions, such as network analysis, and functions that are available through the geoprocessing framework.

A map is a collection of layers. A layer is a thematic representation of geographic information that is stored in a database. An example of a map with layers is shown in the following screen shot:

A map document includes a single layout that contains data frames and marginalia as shown in the following screen shot:

Screen shot showing a single layout map with data frames and marginalia.

MapServer object

The majority of mapping objects reside in the esriCarto and esriDisplay libraries. Typically, mapping applications include objects from a variety of libraries. When working with maps in ArcGIS for Server applications, all interaction is through the MapServer object. The MapServer object is a coarse-grained server object that provides access to the contents of a map document and methods for querying and drawing the map.

The MapServer object is shown in the following illustration:

Illustration showing a MapServer object.

The map Web control is configured to display a specific MapServer running in a GIS server. Likewise, the smart client Map control is also configured to connect to a MapServer's data extraction Web service.

MapServer can be configured as pooled or non-pooled, depending on the requirements of the application. An example of an application requiring a non-pooled MapServer is one that changes the map (for example, adds or removes layers). Another example is an application that manages a geodatabase edit session across multiple requests.

The MapServer coclass contains several interfaces with basic functions for displaying (IMapServer and IMapServerLayout) and querying (IMapServer and IMapServerData) an ArcGIS map document (.mxd or .pmf). There are also associated objects that represent input and output parameters for methods on MapServer interfaces. For example, the IMapServer.ExportMapImage method 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. All the methods on IMapServer are stateless and can be called on both pooled and non-pooled map servers.

The following code example shows how to get a MapServer object from the GIS server and make a call to draw itself at its default extent:

[C#]


        IServerContext pServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer");
IMapServer pMapServer = pServerContext.ServerObject as IMapServer;

IImageType it = pServerContext.CreateObject("esriCarto.ImageType")as ImageType
    it.Format = esriImageFormat.esriImageJPG;
it.ReturnType = esriImageReturnType.esriImageReturnMimeData;

IImageDisplay idisp = pServerContext.CreateObject("esriCarto.ImageDisplay")as
    IImageDisplay;
idisp.Height = 400;
idisp.Width = 500;
idisp.DeviceResolution = 150;

IImageDescription pID = pServerContext.CreateObject("esriCarto.ImageDisplay")as
    IImageDescription;
pID.Display = idisp;
pID.Type = it;

IMapServerInfo pMapServerInfo = pMapServer.GetServerInfo(pMapServer.DefaultMapName);
IMapDescription pMD = pMapServerInfo.DefaultMapDescription;
IImageResult pMI = pMapServer.ExportMapImage(pMD, pID);

// Do something with the result.
pServerContext.ReleaseContext();

[VB.NET]


        Dim pServerContext As IServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer")
Dim pMapServer As IMapServer = pServerContext.ServerObject

Dim it As IImageType = pServerContext.CreateObject("esriCarto.ImageType")
it.Format = esriImageFormat.esriImageJPG
it.ReturnType = esriImageReturnType.esriImageReturnMimeData

Dim idisp As IImageDisplay = pServerContext.CreateObject("esriCarto.ImageDisplay")
idisp.Height = 400
idisp.Width = 500
idisp.DeviceResolution = 150

Dim pID As IImageDescription = pServerContext.CreateObject("esriCarto.ImageDisplay")
pID.Display = idisp
pID.Type = it

Dim pMapServerInfo As IMapServerInfo = pMapServer.GetServerInfo(pMapServer.DefaultMapName)
Dim pMD As IMapDescription = pMapServerInfo.DefaultMapDescription
Dim pMI As IImageResult = pMapServer.ExportMapImage(pMD, pID)

'Do something with the result.
pServerContext.ReleaseContext()

Map and layer objects

To access information about a map and its layers, use the GetServerInfo method from IMapServer. GetServerInfo returns a MapServerInfo object. Use the IMapServerInfo interface to access read-only information about a map (data frame). IMapServerInfo provides access to members describing the default state of a MapServer object, such as the name of the map, the background color, and the spatial extent. This information cannot be changed without changing the state of the underlying fine-grained ArcObjects.

A basic view of map and layer objects, and relationships are shown in the following illustration:

Illustration showing map and layer information objects.

Illustration showing map and layer information objects.

A MapServerInfo object contains a MapDescription. Use IMapDescription to access map settings that can be changed on the server object without changing the state of the underlying fine-grained ArcObjects on which the map document is based.

MapDescription is an important object when using MapServer in a stateless application, such as a Web application or Web service. MapDescription allows you to specify parameters for drawing the map without changing the state of the MapServer object. The application keeps a serialized copy of the map description (created using SaveObject) in session state and deserializes it (using LoadObject) on each request. This allows each user of the application to have their extent, set of visible layers, and so on, but use a pooled MapServer.

Aspects of a map that can be modified in a stateless manner using the map description include the following:

Map extent
Angle of rotation of the map
Color in which selected features are drawn
Color that is drawn transparent
Spatial reference
Graphics

Layer settings can be retrieved from the IMapLayerInfo and ILayerDescription interfaces. Use the IMapLayerInfo interface to access read-only information about an individual layer in the map. Use the ILayerDescription interface to access read and write properties of a layer. As with the map description, the layer description allows you to modify aspects of each layer of the map in a stateless manner.

Aspects of a layer that can be modified in a stateless manner using the layer description include the following:

Visibility of the layer
Definition query expression for the layer
Whether the symbols used to draw the features in the layer scale according to the map's reference scale
Color in which selected features are drawn
Whether selected features draw with a specific symbol, and if so, the symbol with which to draw them
Whether a buffer is included around selected features in the layer
Whether labels configured for the layer are drawn

The following code example shows how to get a MapServer object from the GIS server and make a call to draw itself at its default extent with the first layer in the map not visible:

[C#]


        IServerContext pServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer");
IMapServer pMapServer = pServerContext.ServerObject as IMapServer;

IImageType it = pServerContext.CreateObject("esriCarto.ImageType")as ImageType
    it.Format = esriImageFormat.esriImageJPG;
it.ReturnType = esriImageReturnType.esriImageReturnMimeData;

IImageDisplay idisp = pServerContext.CreateObject("esriCarto.ImageDisplay")as
    IImageDisplay;
idisp.Height = 400;
idisp.Width = 500;
idisp.DeviceResolution = 150;

IImageDescription pID = pServerContext.CreateObject("esriCarto.ImageDisplay")as
    IImageDescription;
pID.Display = idisp;
pID.Type = it;

IMapServerInfo pMapServerInfo = pMapServer.GetServerInfo(pMapServer.DefaultMapName);
IMapDescription pMD = pMapServerInfo.DefaultMapDescription;
ILayerDescriptions pLayerDescs = pMD.LayerDescriptions;
ILayerDescription pLD = pLayerDescs.get_Element(0);
pLD.Visible = false;

IImageResult pMI = pMapServer.ExportMapImage(pMD, pID);

// Do something with the result.
pServerContext.ReleaseContext();

[VB.NET]


        Dim pServerContext As IServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer")
Dim pMapServer As IMapServer = pServerContext.ServerObject

Dim it As IImageType = pServerContext.CreateObject("esriCarto.ImageType")
it.Format = esriImageFormat.esriImageJPG
it.ReturnType = esriImageReturnType.esriImageReturnMimeData

Dim idisp As IImageDisplay = pServerContext.CreateObject("esriCarto.ImageDisplay")
idisp.Height = 400
idisp.Width = 500
idisp.DeviceResolution = 150

Dim pID As IImageDescription = pServerContext.CreateObject("esriCarto.ImageDisplay")
pID.Display = idisp
pID.Type = it

Dim pMapServerInfo As IMapServerInfo = pMapServer.GetServerInfo(pMapServer.DefaultMapName)
Dim pMD As IMapDescription = pMapServerInfo.DefaultMapDescription
Dim pLayerDescs As ILayerDescriptions = pMD.LayerDescriptions
Dim pLD As ILayerDescription = pLayerDescs.Element(0)
pLD.Visible = False
Dim pMI As IImageResult = pMapServer.ExportMapImage(pMD, pID)

'Do something with the result.
pServerContext.ReleaseContext()

Exporting a map image

To export a map image, use the ExportMapImage method on the IMapServer interface. To specify the size and type of the output image, use the IImageDescription, IImageDisplay, and IImageType interfaces. MapServer supports all ArcGIS supported output types. ExportMapImage returns a MapImage object. The IMapImage and ILayoutImage interfaces inherit from IImageResult, which is shown in the previous code example.

The map image exporting objects are shown in the following illustration:

Illustration showing a map image exporting objects.

Querying a map

To perform query operations on a map, use the methods on IMapServer or IMapServer2. These methods include the following:

Find
Identify
QueryFeatureCount
QueryFeatureData
QueryFeatureData2
QueryFeatureIDs
QueryHyperlinks

To control the amount of information MapServer processes during a query, a maximum number of records can be set. This value is set as part of the configuration of the MapServer server object and is not modifiable by application developers. This setting does not affect QueryFeatureCount or QueryFeatureIds.

The Find method returns a MapServerFindResults object. This is a collection of MapServerFindResult objects. Use IMapServerFindResult to access properties of found features. The MapServer find result objects are shown in the following illustration:

Illustration showing MapServer find result objects.

Identify returns a MapServerIdentifyResults object. This is a collection of MapServerIdentifyResult objects. Use IMapServerIdentifyResult to access properties of identified features. This includes rows associated with the feature through a table relationship. The MapServer identify result objects are shown in the following illustration:

Illustration showing MapServer identify result objects.

The following code example shows how to use the QueryFeatureData method on IMapServer to find all the features in the first layer of the map that intersect the MapServer's default map extent:

[C#]


        IServerContext pServerContext = pSOM.CreateServerContext("WorldMap", "MapServer");
IMapServer pMapServer = pServerContext.ServerObject as IMapServer;

IMapServerInfo pMapServerInfo = pMapServer.GetServerInfo(pMapServer.DefaultMapName);
IMapDescription pMD = pMapServerInfo.DefaultMapDescription;

ISpatialFilter pSpatialFilter = pServerContext.CreateObject(
    "esriGeodatabase.SpatialFilter")as ISpatialFilter;
pSpatialFilter.Geometry = pMD.MapArea.Extent;
pSpatialFilter.SpatialRel = esriSpatialRelEnum.esriSpatialRelIntersects;
IRecordSet rs = pMapServer.QueryFeatureData(pMD.Name, 0, (IQueryFilter)
    pSpatialFilter);

// Do something with the result.
pServerContext.ReleaseContext();

[VB.NET]


        Dim pServerContext As IServerContext = pSOM.CreateServerContext("WorldMap", "MapServer")
Dim pMapServer As IMapServer = pServerContext.ServerObject

Dim pMapServerInfo As IMapServerInfo = pMapServer.GetServerInfo(pMapServer.DefaultMapName)
Dim pMD As IMapDescription = pMapServerInfo.DefaultMapDescription

Dim pSpatialFilter As ISpatialFilter = pServerContext.CreateObject("esriGeodatabase.SpatialFilter")
pSpatialFilter.Geometry = pMD.MapArea.Extent
pSpatialFilter.SpatialRel = esriSpatialRelEnum.esriSpatialRelIntersects
Dim rs As IRecordSet = pMapServer.QueryFeatureData(pMD.Name, 0, pSpatialFilter)

'Do something with the result.
pServerContext.ReleaseContext()

Map layouts and map surrounds

As previously described, MapServer serves a map document that contains one or more data frames and a layout. Use the IMapServerLayout interface to export the map layout or to export a legend, north arrow, or scale bar of a map. You can also use IMapServerLayout to convert screen coordinates to page coordinates on the layout and vice versa.

One of the requirements of the ExportLayout method on IMapServerLayout is a PageDescription object. PageDescription contains a MapFrameDescriptions object, which is the collection of MapFrameDescriptions (data frames) present in the layout from which you can get to the MapDescription for each data frame. The page description for a layout is analogous to the map description for a map in terms of how it is used to specify how to draw the layout in a stateless manner. The map description contains a collection of layer descriptions; the page description contains a collection of map frame descriptions (that in turn contain a map description), one for each data frame in the layout.

Individual legend elements

In addition to exporting a single image of the legend using IMapServerLayout, you can retrieve individual legend elements including symbol images, labels, descriptions, and headings. A common use is to populate a table of contents (TOC). To retrieve this legend information, use GetLegendInfo on IMapServer. This method returns a MapServerLegendInfos object, which is a collection of MapServerLegendInfo objects. Using these objects, you can retrieve the specific parts of the legend in which you are interested.

The MapServer legend information objects are shown in the following illustration:

Illustration showing MapServer legend information objects.

Accessing fine-grained ArcObjects

Though the methods and properties available through MapServer and its associated objects offer important mapping functionality, they do not cover all that ArcObjects offers. In many cases, you might want to use other fine-grained ArcObjects in conjunction with MapServer. You can do this by 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. Map services hosted from map service documents (optimized map services) do not provide access to fine-grained ArcObjects.

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

Permanent changes to the MapServer object can be done as follows:

Change the map document and restart the MapServer object.
Change the MapServer properties using interfaces, such as IMapDescription and ILayerDescription, then call the ApplyMapDescription method on IMapServerObjects. This updates the state of the MapServer object.
Change the MapServer object to access the underlying fine-grained ArcObjects directly using the methods on IMapServerObjects, make a change, such as adding a new layer or changing a layer's rendering, then call RefreshServerObjects. This refreshes the MapServer object with the current state held by the fine-grained ArcObjects.

The following code example shows how to use the fine-grained ArcObjects associated with a MapServer object to work with a feature class associated with a particular layer:

[C#]


        IServerContext pServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer");
IMapServer pMapServer = pServerContext.ServerObject as IMapServer;

IMapServerObjects pMapServerObjs = pMapServer as IMapServerObjects;
IMap pMap = pMapServerObjs.get_Map(pMapServer.DefaultMapName);

IFeatureLayer pFLayer = pMap.get_Layer(0)as IFeatureLayer;
IFeatureClass pFeatureClass = pFLayer.FeatureClass;
Console.WriteLine(pFeatureClass.FeatureCount(null).ToString());

pServerContext.ReleaseContext();

[VB.NET]


        Dim pServerContext As IServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer")

Dim pMapServer As IMapServer = pServerContext.ServerObject
Dim pMapServerObjs As IMapServerObjects = pMapServer
Dim pMap As IMap = pMapServerObjs.Map(pMapServer.DefaultMapName)

Dim pFLayer As IFeatureLayer = pMap.Layer(0)
Dim pFeatureClass As IFeatureClass = pFLayer.FeatureClass
Debug.WrtieLine (pFeatureClass.FeatureCount(Nothing))

pServerContext.ReleaseContext()