The majority of GIS applications are based on one or more maps, wether a map is the result or output of an application, or the map is the central aspect of the application that users interact with. ArcGIS Server applications are no different.
A map is a collection of layers of geographic information, graphic elements and has 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) which are created using the ArcMap desktop application. Within 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 marganalia.
You interact with maps, layouts and layers in a variety of ways:
- Pan and zoom interactivly
- 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 geogrphic 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 representaion of geographic infomormation that is stored in a database.
A map document includes a single layout that contains data frames and marginalia.
To exploit map documents and their contents through ArcGIS Server applications, ArcGIS Server includes a MapServer server object. The MapServer object provides access to the contents of a map document and methods for querying and drawing the map.
The majority of the mapping objects are found in the esriCarto and esriDisplay libraries. Typically, your mapping applicaiton will include the use of objects in a variety of libraries. When working with maps in ArcGIS Server applications, all such interaction is through the MapServer.
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 a coarse-grained server object that provides access to the contents of a map document and methods for querying and drawing the map. 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 extractionWeb service.
It's not uncommon for a MapServer to be configred as pooled or non-pooled, depending on the requirements of the application. Examples of when an application would require a non-pooled MapServer is one that changes the map (for example adds or removes layers), or 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). Also, there are a number of associated objects that 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. All the methods on IMapServer are stateless and can be called on both pooled and non-pooled MapServers.
The following code is an example of getting a MapServer object from the GIS server and making a call to draw itself at its default extent:
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();
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()
Information about the map and its layers
To access information about a map and its layers use the IMapServer method GetServerInfo . 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 or the spatial extent of the map. This information cannot be changed without changing the state of the underlying fine-grained ArcObjects.
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 that the map document is based on.
The MapDescription is an important object when using the MapServer in a stateless application, such as a web application or web service. The MapDescription allows you to specify parameters for how you want the map to be drawn without changing the state of the MapServer object itself. The application keeps a serlialized copy of the map description (created using SaveObject) in session state and deserlializes it (using LoadObject) on each request. This allows each user of the application to have their own 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 extent of the map
- The angle of rotation of the map
- The color which selected features are drawn
- The color that will be drawn transparent
- The map's spatial reference
- Graphics to draw on the map
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. Like the map description, the layer description allows you to modify aspects of each layer of the map in a stateless way. Aspects of a layer that can be modified in a stateless manner using the layer description include:
- The visibility of the layer
- The definition query expression for the layer
- Whether the symbols used to draw the features in the layer should scale according to the map's reference scale
- The color with which selected features are drawn
- Whether selected features should be drawn with a specific symbol, and if so, the symbol to draw them with
- Wether a buffer should be included around selected features in the layer
- Whether the labels configured for the layer should be drawn or not
The following code is an example of getting a MapServer object from the GIS server and making a call to draw itself at its default extent with the first layer in the map not visible:
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();
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()
The map control's webmap object handles modifying, saving and restoring the map and layer descriptions as users interact with the map and table of contents web controls. This is described in more detail in `Web controls and session state' later in this section.
Exporting a map image
To export a map image use the method ExportMapImage on the interface IMapServer. 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 interfaces IMapImage, along with ILayoutImage inherit from IImageResult. This is demonstrated in the code examples above.
Querying the map
To perfom query operations on the map, IMapServer offers a number of methods. These include: Find, Identify, QueryHyperlinks, QueryFeatureCount, QueryFeatureData, and QueryFeatureIDs. In order to control the amount of information MapServer needs to process for a query, a maximum number of records can be set. This value is set as part of configuring the MapServer server object and is not modifyable 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.
Identify returns a MapServerIdentifyResults object. This is a collection of MapServerIdentifyResult objects. Use IMapServerIdentifyResult to access properties of identified features. This includes rows associated to the feature through a table relationship. 
The following code 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:
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();
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 somthing with the result
pServerContext.ReleaseContext()
Map layouts and map surrounds
Ad described earlier, a MapServer serves a map document that contains one or more data frames, and also contins a layout. Use the IMapServerLayout interface to export the map layout or to export a legend, North arrow or a scale bar of a map. Also use IMapServerLayout to convert screen coordinates to page coordinates on the layout and vice versa.
One of the requirements for the ExportLayout method on IMapServerLayout is a PageDescription object. The 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 analgouse to the map description for maps in terms of how it is used to specify how to draw the layout in a stateless manner. Like the map description contains a collection of layer descriptions, the page description contains a collection of map frame descriptions (which in turn contain a map description), one for each data frame in the layout.
Information about individual legend elements
In addition to exporting a single image of the legend using IMapServerLayout, you can retrieve individual legend elements including the symbol images, labels, descriptions and headings. A common use would be to populate a table of contents. 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 only the parts of the legend you are interested in. 
Accessing fine-grained ArcObjects
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 its default state.
Permanent changes to the MapServer object can be done in three ways. The first is by changing the map document itself and then restarting the MapServer object. The second 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 MapServer object. The third way to change the MapServer object is 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, and then calling RefreshServerObjects. This refreshes the MapServer object with the current state held by the fine-grained ArcObjects.
The following code is an example of using the finer-grained ArcObjects associated with a MapServer object to work with a feature class associated with a particular layer:
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();
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()