Working with the Map control

In this topic

Refresh map content

When the Map's content changes—for example, the layer visibility was toggled, or custom graphics were added or removed—you can choose the Refresh or RefreshResource methods to programmatically refresh the Map.  
The Map.Refresh() method triggers a complete redraw of all resources on the Map and can be time consuming, especially if only one resource changed. Map.RefreshResource() provides the most efficient way to refresh Map content. 
When the Map control uses "browser blending" to combine map images, a call to RefreshResource() only refreshes the resource that it requires. When the Map control uses "Web-tier blending," a call to RefreshResource() calls Refresh() on the Map and all content is rendered again. The RefreshResource() method contains internal logic to interrogate map blending mode and determine if an individual resource, or all resources need to be redrawn.   

Set map's initial extent during application startup

At design time, the InitialExtent property of a Map control can be set to default or full.  
  • Default uses the extent of the primary map resource. 
  • Full uses an extent that includes all resources on the map. 
To explicitly set the extent of the Map control upon application initialization, add the appropriate code to the PreRender event of the page or map. 
The following code example uses a custom Web Application Developer Framework (ADF) envelope to define the initial extent of the map. Set the initial extent on the initial request to the application, not on every subsequent postback. 
[C#] 
protected void Page_PreRender(object sender, EventArgs ea)
{
    if (!Page.IsPostBack)
    {
        ESRI.ArcGIS.ADF.Web.Geometry.Envelope initextent = new
            ESRI.ArcGIS.ADF.Web.Geometry.Envelope( - 110, 30,  - 100, 40);
        Map1.Extent = initextent;
    }
}
[VB.NET] 
Protected Sub Page_PreRender(sender As Object, ea As EventArgs)
If Not Page.IsPostBack Then
    Dim initextent As New ESRI.ArcGIS.ADF.Web.Geometry.Envelope( -110, 30, -100, 40)
    Map1.Extent = initextent
    EndIf
End Sub

Create single blended map image

On Microsoft Windows platforms, the Graphics Device Interface (GDI) is used to draw graphics on windows, forms, and other displayed media. GDI consists of a set of C++ classes. The Microsoft .NET Framework provides access to GDI capabilities via GDI+, which consists  of a set of .NET classes that enhances rendering and manipulation of graphics and images. GDI+ can also be used to merge (or blend) multiple images into a single image. 
A Web ADF Map control uses one map functionality for each map resource to generate a map image; therefore, a Map that works with multiple resources generates multiple images. For each map extent, all generated map images are blended in the Web browser or the Web-tier. In either case, you see what appears to be one map when in fact, it can consist of many overlapping images. In some cases, it might be necessary to blend all map images into a single image for use outside of the Map control. For example, generating a printable map from a Map control that contains multiple map resources often requires programmatically merging all map images into one. In .NET, you can use GDI+ to generate a single blended image. 
The following code example iterates through the MapFunctionality instances on a Map to generate a single blended map image. The imgwidth and imgheight determine the size of the map image in pixels. When finished, the GDI+ System.Drawing.Bitmap referenced by the newimg variable contains the blended map.
[C#] 
ArrayList bitmaps = new ArrayList();
foreach (IMapFunctionality mf in Map1.GetFunctionalities())
{
    mf.DisplaySettings.ImageDescriptor.Height = imgheight;
    mf.DisplaySettings.ImageDescriptor.Width = imgwidth;
    mf.DisplaySettings.ImageDescriptor.TransparentBackground = true;
    mf.DisplaySettings.ImageDescriptor.ImageFormat =
        ESRI.ArcGIS.ADF.Web.ImageFormat.PNG8;
    ESRI.ArcGIS.ADF.Web.MapImage mi = mf.DrawExtent(Map1.Extent);
    bitmaps.Add(mi.GetImage());
}

System.Drawing.Bitmap newimg = new System.Drawing.Bitmap(imgwidth, imgheight);
System.Drawing.Graphics imggraphics = System.Drawing.Graphics.FromImage(newimg);
imggraphics.FillRectangle(new System.Drawing.SolidBrush
    (System.Drawing.Color.LightGray), 0, 0, imgwidth, imgheight);
for (int j = bitmaps.Count - 1; j >= 0; j--)
{
    System.Drawing.Bitmap bmp = (System.Drawing.Bitmap)bitmaps[j];
    imggraphics.DrawImage(bmp, 0, 0, imgwidth, imgheight);
}

Set spatial reference

The spatial reference of a Map control is set during application initialization and cannot be changed at runtime. The primary resource of a Map control determines the spatial reference of the map. To set the spatial reference of the map, define the appropriate coordinate system for the primary map resource. Secondary map resources will be projected again into the map's spatial reference if the data source supports projecting again on the fly. 

Define primary map resource

A Map's primary map resource is used to define the spatial reference, rotation (if present), initial extent, scale, and zoom levels. The PrimaryMapResource property can be explicitly set to a map resource item or left blank. If left blank, the logic in the following table is used to determine the primary map resource:
Map resource
Primary map resource
One dynamic or one cached resource
If only one resource is available, it is the primary map resource.
Two dynamic resources
Last resource in the resource items collection.
Two cached resources
First cached resource in the resource items collection.
One dynamic and one cached resource
First cached resource in the resource items collection.
If you are overlaying multiple cached services with the same spatial reference and matching scales, choose either cached service as the primary map resource. In this scenario, the ZoomLevel control includes the scale levels from all cached services.
If you are overlaying multiple cached services with different spatial references or scales, choose the service whose spatial reference you want used on the map as the primary map resource. The ZoomLevel control only includes scale levels from this service. Images from the other cached service is drawn dynamically to match the coordinate system and scales of the primary map resource (meaning, the cache from the non-primary map resource will not be used). 
If you are overlaying a cached service with a dynamic service, choose the cached service as the primary map resource. If the dynamic service is the primary map resource, the cached service is treated as a dynamic service; therefore, sacrificing the performance benefit of the cache.
Do not set the primary map resource to a graphics layer map resource item. Graphics layers represent Web ADF graphics datasets, which are designed to be utilized programmatically at runtime. As a result, a graphics layer does not have the spatial properties (for example, spatial reference, scale, and so on) the Map needs to initialize and function properly. Also, if you have not explicitly defined a primary map resource, make sure the last resource item is not a graphics layer.

Rotate map content

The Map control's Rotation property can be used to specify, in degrees, the rotation of resources on the Map. Map rotation is supported for ArcGIS for Server (Internet and local) and Web ADF graphics data sources.
  • A "not a number" (NaN) value means that the rotation of the PrimaryMapResource is applied.
  • A "0" value removes rotation from rotated resources and leaves other resources alone.
  • Values greater or less than 0 rotate resources, throwing an exception if resources that are not rotated are available.
The following occurs if the Map control has a rotation value greater or less than 0:
  • Resources that are not rotated return an exception on the Web page at runtime. The exception indicates the resource that does not support rotation.
  • ContinuousCallback and EnableTileCaching properties on the Map control are disabled.
If the Map Rotation property is NaN, the rotation of the PrimaryMapResource can be used. Since a Web ADF graphics resource cannot be a PrimaryMapResource, only a rotation value specified for a data frame in an ArcGIS for Server map service can be used. Map rotation can also be set on-the-fly at runtime.
If the resources in the Map control support rotation, map contents will be updated. If a resource does not support rotation, an exception returns on the Web page indicating the resource. 
The following code example shows how to change the Rotation property programmatically on a Map control:
[C#] 
Map1.Reset();
Map1.Rotation = 45;
Rotating an ArcGIS for Server cached map service requires that dynamic map images are generated (cached map tiles will not be used). As a result, many of the performance benefits of a cached map service are negated. Web controls that work with the Map control also support rotation, such as the Navigation control, Magnifier control, and OverviewMap control.

Image blending mode

The ImageBlendingMode property on a Map control determines how map images from each resource are drawn. This property only has an effect when multiple resources (services) are used on a Map. A graphics layer counts as a resource for drawing purposes.
The following options (browser blending and Web-tier blending) are available for ImageBlendingMode:
  • Browser blending—The default, causes the Web browser to retrieve the map images separately for each resource. The images might be retrieved via static uniform resource locators (URLs) or as streamed Multipurpose Internet Mail Extensions (MIME) data. The Web browser then draws the images for each resource (service), one on top of the other. The advantage of browser blending is that a resource can be refreshed without refreshing other resources. For example, feature selection highlights can be drawn on a graphics layer without refreshing the underlying map.

    The following illustration shows browser blending in which the Web application uses map services on two different servers. The Web browser retrieves each map separately and superimposes them together so they appear as a single map.


  • Web-tier blending—Causes the Web ADF on the server to retrieve all map images from map services used on the Web site. The Web application merges the images for all resources into a single image. The merged image is then sent to the Web browser. The following illustration shows Web-tier blending:

Use browser blending unless you have a specific reason to have the server blend map images.

Resource centric tiling scheme

To display map data within a Map control, map resources either generate an image on-the-fly or retrieve a cached image tile. Each resource can define and utilize a tiling scheme to provide more effective and efficient interaction with the resource on the map.    
Non-cached (dynamic) map resources have the option of using or not using a dynamic tiling scheme. A dynamic tiling scheme is constructed on-the-fly at runtime using the extent, size, and scale of the map. As long as the scale remains the same, the tiling scheme remains valid and continues to manage the retrieval of dynamic map images. This benefits resources that generate map images relatively quick and application scenarios in which you will frequently pan. 
Web browser cache is used to render dynamic images already generated for a tile in the scheme. If a non-cached resource does not enable dynamic tiling, each extent changed on the map generates a new dynamic map image, and Web browser cache is not utilized. Choose enable or disable dynamic tiling when you create a map resource item (for example, at design time using the MapResourceManager control). 
The following table shows the default tiling scheme settings for each data source type:
Data source type
Dynamic tiling default
ArcGIS for Server local
disabled
ArcGIS for Server Internet
disabled
ArcIMS
enabled
Open Geospatial Consortium (OGC) and Web Map Server (WMS)
disabled
Graphics
enabled
Cached (tiled) map resources always utilize the tiling scheme defined by the map service host. The scheme information provided by the service includes the spatial reference, full extent, tile image properties, and cached levels of detail, each of which defines a scale, and number of rows and columns. The map resource item uses this information with the Map control extent to determine the cache tiles that need to be retrieved. Since the number of levels remain the same regardless of the map extent, map tiles can be cached by the Web browser in multiple levels. This enhances the performance of cached services on the Map because once a map tile is cached by the Web browser, it can be reused. 
The following illustration shows the runtime behavior of resource items with different tiling schemes during a simple pan operation on the map. The "pre" and "post" pan extent of the map view shows as orange boxes at the bottom of the illustration. Each resource item type shows the pre (gray) and post (green) map images retrieved from a remote server. 
  • For non-cached (dynamic) resources that have dynamic tiling enabled, the pre pan map view establishes the tiling scheme for the resource and requests one map image (gray). After the pan event, three map images are generated because the map view extent intersects three tiles in the scheme.   
  • For non-cached resources that "do not" have tiling enabled, each map view extent generates one new map image. For cached resources, cached map tiles that intersect the map view extent are retrieved. 
The following illustration shows four tiles requested before the pan and two tiles requested after the pan event:

Cached tile retrieval

The Map control can obtain map images from an ArcGIS for Server map service as tiles already created, rather than dynamically drawing the map on the server. For more information on map caching, see What is Map caching?.
Tile retrieval depends on the following factors:
  • Whether the Map control's ImageBlendingMode property is set to browser blending or Web-tier blending. If only one resource (service) is added to the map, or only one resource is currently visible, browser blending is used even if Web-tier blending is enabled.
  • Whether a cache virtual directory was configured for the service in ArcCatalog or Manager.
  • Connection method to the service, that is, ArcGIS for Server local or ArcGIS for Server Internet.
  • Security settings. If a cache virtual directory is configured, tile retrieval differs depending on whether the virtual directory is secured to require authentication. If security is applied, the Web application can get tiles whether it provides credentials or not, but the way it retrieves tiles differs. If no cache virtual directory is configured, and if using an ArcGIS for Server Internet connection, retrieval differs depending on whether the Web service is secured to require authentication. If authentication is required, but the Web application or Web browser fails to provide correct credentials for the tile virtual directory, the tile can still be retrieved through a different and less efficient mechanism.

    The following illustration shows how the Web browser and Web application retrieves map tiles based on the preceding factors. Some retrieval approaches are more efficient than others. See the tables that follow the illustration for details on each tile retrieval mechanism.

  • JavaScript—Indicates that the Web browser retrieves the map tile directly from the Web server, without interacting with the Web application.
  • Tile handler—Indicates that the Web browser requests the tile from a Hypertext Transfer Protocol (HTTP) handler (TileHandler.ashx) within the Web application. The handler retrieves the tile using the information in the request query string. It also accesses information in the user session.
In the following tables, access methods are listed in decreasing order of expected efficiency:
Tile retrieval ( Browser blending)
JavaScript
Virtual directory
Most common scenario when defaults are used to set up the map service and Web application, and no security is applied to the map service. It is also the fastest way to retrieve map tiles.
JavaScript
Tile Web service
Web browser calls a HTTP handler on the Web service running on the ArcGIS for Server machine that reads the image from disk and returns the image as a stream of bytes.
Tile handler
Virtual directory
Web browser calls a HTTP handler (TileHandler.ashx) on the Web ADF server that uses credentials to access a secured virtual directory and returns the image as a stream of bytes.
Tile handler
Tile Web service
Web browser calls a HTTP handler (TileHandler.ashx) on the ADF server that uses credentials to access a HTTP handler on an ArcGIS for Server machine. The handler on the ArcGIS for Server machine reads the image from disk and streams back the image as a series of bytes.
Tile handler
GetMapTile
Web browser calls a HTTP handler (TileHandler.ashx) on the ADF server that in turn, calls a Web service method that returns image bytes. The HTTP handler streams back the bytes of the image. In this case, the ArcGIS server object manager (SOM) and server object container (SOC) are used to retrieve the tile.
Tile retrieval (Web-tier blending)
Web-tier
Virtual directory
During page life cycle, the image is read from the virtual directory and is blended to overlay with other resources (layers) on the map. The blended image is then sent to the Web browser.
Web-tier
GetMapTile
During page life cycle, the image is retrieved from a HTTP handler on the ArcGIS for Server machine. The handler on the ArcGIS for Server machine reads the image from disk and streams back the bytes. The image is blended to overlay with other resources (layers) on the map. The blended image is then sent to the Web browser.
Web-tier
Tile Web service
During page life cycle, the image is retrieved through a Web service method that returns image bytes. The image is blended to overlay with other resources (layers) on the map. The blended image is then sent to the Web browser.

MapHandler

By default, map draw operations do not iterate through the page life cycle. Instead, a HTTP handler—ESRI.ArcGIS.ADF.Web.UI.WebControls.MapHandler—is solely responsible for managing map draw operations. Other actions, such as those initiated from map tools, commands, map events, or Toc control changes, still iterate through the page life cycle. The MapHandler enhances map draw performance by skipping the page life cycle when drawing the map, which reduces the amount of processing overhead. The EnableMapHandler property on the Map control enables you to choose whether you use the MapHandler or iterate through the page life cycle for map draw operations. 
  
One scenario where you might choose to iterate through the page life cycle is when using pre-9.3 patterns for managing shallowly stateful operations. For example, in 9.2, managing stateful changes to a pooled server object (shallowly stateful) was possible, given the ability to access server context at the appropriate time to modify and reset the server object. 
Since all Web requests associated with Web ADF components in a Web application traversed the page life cycle (including map draw, queries, table of contents ([TOC] changes), managing a server object involved managing when to modify the server object in the life cycle. Setting the EnableMapHandler property to false enables this pattern to function in 9.3.  
In this scenario, you can choose to take advantage of the performance enhancement offered by the MapHandler. The MapHandler offers a set of events to override and modify resources before and after map draw. To override the events, create a class derived from the MapHandler class, define the events to override, and add a reference to the custom MapHandler in the Web.config file. 
Changes to the server object state needs to be duplicated or shared for map draw and all other Web requests. If the code used to manage shallowly stateful operations is packaged in a single class or assembly, events in the custom MapHandler and page life cycle can share the same code logic. For more information on this procedure, see ArcGIS Add dynamic data.

Default keyboard and mouse shortcuts

The following table shows default keyboard and mouse shortcuts for the Map control:
Shortcut
Map action
Shift, left mouse click, hold and drag box
Zoom in
Ctrl, left mouse click, hold and drag box
Zoom out
Left mouse click, hold and drag
Pan
Num Lock disabled, use keypad
Pan
Arrow keys, Home, End, Page Up, Page Down
Pan
Num Lock enabled, +
Zoom in
Num Lock enabled, -
Zoom out


See Also:

Map control
What is Map caching?
Sample: ArcGIS Add dynamic data