Map resources

In this topic

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

About map resources

Map resources provide access to map data, such as map images (dynamic and static), feature symbolization and rendering, and feature attributes. Map resources are available in a Web Application Developer Framework (ADF) application via a MapResourceManager control.
Map resources are managed by the MapResourceManager control. Map resources are implemented by the following:
  • ArcGIS for Server local
  • ArcGIS for Server Internet
  • ArcIMS
  • OGC WMS
  • Bing Maps
Functionality types created by map resources are as follows: 
  • IMapFunctionality
  • IQueryFunctionality
  • IMapTocFunctionality
  • ITileFunctionality
  • IScalebarFunctionality
The IMapResource interface defines the generic properties used to store display settings, such as transparency of the map image generated by the resource, and map information, such as default extent and spatial reference details.
The following table lists properties and methods available to map resources via the IMapResource interface:
Property or method
Description
CreateFunctionality() method
Available via the IGISResource interface. Often used to create a QueryFunctionality.
DisplaySettings property
Accesses and configures map display settings, such as transparency, transparent background color, and visibility.
MapInformation property
Accesses map resource defaults for extent and spatial reference.
SupportsFunctionality() method
Available via the IGISResource interface. Used to determine if a functionality type is supported by a resource.
The following code example shows how to generically access and work with a map resource if you do not know the underlying data source:
[C#] 
IMapResource mapresource = MapResourceManager1.GetResource(0);
mapresource.DisplaySettings.Visible = true;
mapresource.DisplaySettings.Transparency = 50.0F;
This code uses the common data source application programming interface (Common API) IMapResource. No specific data source is mentioned. The first resource in the MapResourceManager control is returned, its visibility is set to true, and the transparency for the map image generated by the resource is set to 50 percent (or 50.0). The MapResourceManager1 variable references the MapResourceManager control.
Data source-specific implementations of IMapResource can provide data source-specific references. To get a reference to a data source-specific map resource, cast to the appropriate type.

Supported data sources

Each supported data source, its namespace, and the unique capabilities it provides are covered in the following sections.

ArcGIS for Server

The namespace for ArcGIS for Server is ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer. Both ArcGIS for Server local and ArcGIS for Server Internet data sources share implementation details from the MapResourceBase (map services) abstract base class and the ImageResourceBase (image services) class. Since both data sources work with services using the ArcGIS for Server Simple Object Access Protocol (SOAP) API, some properties and methods are shared. Both work with value objects in the Web ADF and communicate with the geographic information system (GIS) server using a proxy class. For more information, see ArcGIS for Server implementation in the Web ADF.
The following tables list shared properties for MapResourceBase and ImageResourceBase:
MapResourceBase property
Description
MapDescription
Accesses and modifies a reference to a MapDescription Value object. Used by the Web ADF for state management.
MapServerProxy
Accesses the MapServerProxy used to manage SOAP requests and responses to an ArcGIS for Server service.
Service
Name of the map service used by the map resource.
ImageResourceBase property
Description
ImageResourceDefinition
 Accesses the image resource definition, which contains the GeoImageDescription used to generate a new map image.
ImageServerProxy
Accesses the ImageServerProxy used to manage SOAP requests and responses to an ArcGIS for Server service.
ImageServiceInfo
Provides information about the image service.
Service
Name of the image service used by the map resource.
If you do not need to work with a specific capability of a local or Internet type of ArcGIS for Server resource, you can use a reference to the base class. The following code example shows how to retrieve the name of an ArcGIS for Server service via the MapResourceBase class:
[C#] 
IMapResource mapresource = MapResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceBase ags_mapresourcebase = 
    (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceBase)mapresource;
string ags_servicename = ags_mapresourcebase.Service;
  • ArcGIS for Server local—ArcGIS for Server local resources manage server context and work with ArcGIS for Server services via a server object. Local implementation is handled within the MapResourceLocal class. You do not need to explicitly create and release server context when you're working with a server object as a Web ADF resource. The Web ADF resource manager control manages server context for you.

    The following table lists properties and methods available via the MapResourceLocal class:
Property or method
Description
ApplyMapDescriptionToServer() method
Makes a stateful change to the server object instance on the GIS server. Applies the current MapDescription resource to the server object. Usually called once changes to a MapDescription are saved to a server object instance. Uses the ESRI.ArcGIS.Carto.IMapServerObjects ApplyMapDescription() method.
MapServer property
Accesses ArcObjects IMapServer.
MapServerProxy property
Accesses the MapServerDcomProxy used to manage SOAP requests and responses to a server object via the IRequestHandler interface.
RefreshServerObjects() method
Makes a stateful change to the server object instance on the GIS server. Applies the fine-grained ArcObjects changes to the server object instance. Uses the ESRI.ArcGIS.Carto.IMapServerObjects RefreshServerObjects() method.
ServerContextInfo property
Accesses a ServerContextInfo object, which exposes access to server context, server object name, and type.
The following code example shows how to create a Component Object Model (COM) object on the GIS server using server context:
[C#] 
IMapResource mapresource = MapResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceLocal ags_mapresourcelocal =
    (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceLocal)mapresource;
ESRI.ArcGIS.Server.IServerContext com_servercontext =
    ags_mapresourcelocal.ServerContextInfo.ServerContext;
ESRI.ArcGIS.Geometry.IPoint com_point = (ESRI.ArcGIS.Geometry.IPoint)
    com_servercontext.CreateObject("esriGeometry.Point");
  • ArcGIS for Server Internet—ArcGIS for Server Internet resources work with ArcGIS for Server services via a Web service endpoint. Internet implementation is handled within the MapResourceInternet class. You do not have access to server context via an ArcGIS for Server Web service. Communication with a ArcGIS for Server Web service is only available via the ArcGIS for Server SOAP API.

    The following table lists properties available via the MapResourceInternet class:
Property
Description
MapServerProxy
Accesses the MapServerProxy used to manage SOAP requests and responses to a Web service endpoint.
Url
The uniform resource locator (URL) string to the ArcGIS for Server Web service endpoint for the map resource.

The following code example shows how to call a method on the Web service proxy to get the default map name of an ArcGIS for Server service associated with an ArcGIS for Server Internet map resource:
[C#] 
IMapResource mapresource = MapResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceInternet
    ags_mapresourceinternet = 
    (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceInternet)mapresource;
ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy ags_mapserverproxy =
    ags_mapresourceinternet.MapServerProxy;
string ags_defaultmapname = ags_mapserverproxy.GetDefaultMapName();

ArcIMS

The namespace for ArcIMS is ESRI.ArcGIS.ADF.Web.DataSources.IMS. ArcIMS resources work with ArcIMS, ArcMap, and image services via Hypertext Transfer Protocol (HTTP) or Transmission Control Protocol (TCP). The ArcIMS API is the implementation framework for ArcIMS capabilities in the Web ADF. The MapService and MapView classes in the ArcIMS API work with an ArcIMS map service. ArcIMS is inherently stateless, but ArcIMS MapResource can maintain state on the client (Web-tier). As a result, changes to MapService or MapView can be maintained for the duration of a session. In most cases, you will work with MapView from ArcIMS MapFunctionality to interact with ArcIMS-specific capabilities.
The following table lists properties available via the ArcIMS MapResource class:
Property
Description
MapService
Accesses the ArcIMS API ESRI.ArcGIS.ADF.IMS.Carto.MapService object. Default extent, connection, and service information are available.
MapView
Accesses the ArcIMS API ESRI.ArcGIS.ADF.IMS.Carto.MapView object. The MapView object is the primary object for working with an ArcIMS map service. It generates map images, queries features, extracts data, and so on.
The following code example shows how to use the ArcIMS MapResource MapService property to get an ArcIMS service name:
[C#] 
IMapResource mapresource = MapResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapResource ims_mapresource = 
    (ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapResource)mapresource;
ESRI.ArcGIS.ADF.IMS.Carto.MapService ims_mapservice = ims_mapresource.MapService;
ESRI.ArcGIS.ADF.Connection.IMS.IMSServerConnection ims_connection =
    ims_mapservice.Connection;
string ims_mapservicename = ims_connection.ServiceName;

OGC WMS services

The namespace for OGC WMS services is ESRI.ArcGIS.ADF.Web.DataSources.OGCWMSService. Open Geospatial Consortium (OGC) Web Map Service (WMS) services are based on an open source standard for providing map data over the Web. Each map resource is associated with a unique URL defined by a hostname, path, and a set of argument and value pairs. For additional information on the WMS interface standard, see the OGC Web site. Since working with a WMS is defined by URL parameters, an API separate from the Common API implementation is not included with the Web ADF.
The following table lists properties available via the OGC WMS services MapResource class:
Property
Description
ServiceDefinition
Accesses a string of layer IDs in the WMS.
Website
Accesses the Web site URL of the WMS.
The following code example shows how to use the OGC WMS MapResource Website property to get the URL to a remote WMS:
[C#] 
IMapResource mapresource = MapResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.OGCWMSService.MapResource ogc_mapresource = 
    (ESRI.ArcGIS.ADF.Web.DataSources.OGCWMSService.MapResource)mapresource;
string ogc_url = ogc_mapresource.Website;

Graphics

The namespace for Graphics resources is ESRI.ArcGIS.ADF.Web.DataSources.Graphics. Graphics resources are maintained in-memory by the Web ADF on the Web-tier. They can be added to MapResourceManager but are utilized programmatically. A graphics resource is a standard ADO.NET dataset extended by the Web ADF to store temporary features. An ADO.NET dataset can contain multiple data tables. Likewise, a Web ADF graphics resource can contain multiple graphics layers. The Web ADF Graphics API utilizes numerous classes in the ESRI.ArcGIS.ADF.Web assembly. For more information on graphics layer types, see Working with graphics.
The following table lists the property available via the Graphics MapResource class:
Property
Description
Graphics
Accesses ESRI.ArcGIS.ADF.Web.Display.Graphics.GraphicsDataSet. GraphicsDataSet manages rendering one or more graphics layers.
The following code example shows how to add a new, empty ElementGraphicsLayer to GraphicsDataSet for a Graphics map resource:
[C#] 
IMapResource mapresource = MapResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource graphics_mapresource = 
    (ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource)mapresource;
ESRI.ArcGIS.ADF.Web.Display.Graphics.ElementGraphicsLayer eglayer = new
    ESRI.ArcGIS.ADF.Web.Display.Graphics.ElementGraphicsLayer();
graphics_mapresource.GraphicsDataSet.Add(eglayer);

Map functionalities

In most cases, you will work with a map resource from the perspective of an existing Map control, which means you will access MapFunctionality first.

MapFunctionality and IMapFunctionality

The Map control is the primary consumer of map resources. A map uses each map resource to generate a map functionality. The MapFunctionality class provides a Resource property to get a reference to a generic IMapResource interface and a MapResource property to get a reference to data source-specific MapResource class. The Map control provides the following methods to get one or more functionality instances:
  • Map.GetFunctionalities()—Returns a list of IMapFunctionality instances.
  • Map.GetFunctionality(argument)—Returns a single IMapFunctionality instance based on the argument value, an index, or resource name.
MapFunctionality is generally used to do to one of the following:
  • Obtain metadata about a map resource, such as a list of layer names and IDs, scale, or spatial reference
  • Draw a map
  • Work with data source-specific capabilities of a map resource
The following table lists properties and methods of IMapFunctionality:
Property or method
Description
DisplaySettings property
Accesses properties and methods used to change the display of a map image generated by the functionality.
DrawExtent() method
Creates a map image.
GetLayers() method
Gets array or layer names and IDs in the map resource.
GetLayerVisibility() method
Gets layer visibility in the map.
GetScale() method
Returns the scale (map units per pixel) using the current state of the map functionality.
MaintainsState property
Determines if the Web ADF uses the functionality or resource to maintain state. Changes the reference of the business object (if available) and the DisplaySettings reference.
SetLayerVisibility() method
Sets layer visibility in the map.
SpatialReference property
Accesses the spatial reference of the map resource.
Supports() method
Determines if an operation is supported by the functionality. The operation is the name of a member of the functionality (for example, property or method). For example, to check if the GetScale() method is supported, pass the GetScale string as the operation to the Supports() method. True is returned if the operation is supported; false is returned if it is not supported.
As a Common API interface, IMapFunctionality can be used generically if you do not know the data source type. A map functionality is considered a single layer in a Web ADF Map control, but the map functionality can contain many layers. To get a list of layer IDs and names for each map functionality in a Map control, use the GetFunctionalities() method on the Map control and use the GetLayers() method on the map functionality. When working completely within the Common API, no specific data source is referenced as shown in the following code example:
[C#] 
IEnumerable func_enum = Map1.GetFunctionalities();
foreach (ESRI.ArcGIS.ADF.Web.DataSources.IGISFunctionality gisfunctionality in
    func_enum)
{
    ESRI.ArcGIS.ADF.Web.DataSources.IMapFunctionality mf;
    mf = (ESRI.ArcGIS.ADF.Web.DataSources.IMapFunctionality)gisfunctionality;
    string[] layerids;
    string[] layernames;
    mf.GetLayers(out layerids, out layernames);
}
One important aspect of a map functionality is that the Web ADF uses it to maintain state for the duration of a user session. A map functionality stores references to objects associated with map generation, such as visible layers, image properties, and a data source-specific business object. The Web ADF utilizes data sources in a stateless manner, meaning no state is stored by the data source. Instead, the Web ADF is shallowly stateful, which means it stores state on the client (Web-tier). As a result, you can change properties of a map functionality at run time and have them maintained for the duration of the current session. For example, when adding server-side graphics to a MapFunctionality—for example, GraphicElements to MapDescription for ArcGIS for Server data sources or an AcetateLayer to a MapView for ArcIMS data sources—they are maintained across requests to the data source, without re-adding or explicitly managing the graphics.
For more information about data source-specific implementations of IMapFunctionality, see Data source-specific APIs. Of the available functionalities and resources, only MapFunctionality and MapResource maintain state.

State management and the MaintainsState property

Each MapFunctionality can work with one or more business objects that hold state for a specific data source. For ArcGIS for Server MapFunctionality, it is MapDescription; for ArcIMS MapFunctionality, it is MapView. MapResource also exposes an object of the same type with the sample property reference. MapFunctionality has a MaintainsState property that is a Boolean. If MaintainsState is true, the business object (MapDescription or MapView) exposed by the MapFunctionality is different than the one at the MapResource level. If MaintainsState is false, which is the default, MapFunctionality.MapDescription is a pointer to its resources copy of MapDescription. As a result, modifications to MapDescription are reflected in all MapFunctionality instances that share the same resource.
How state is used depends on the application requirements. The MaintainsState property allows MapFunctionality to have control over its own state, if the use case calls for it. Such a use case might be a magnify window that is accessing the same data as the map, but at a different extent. The MapFunctionality that the magnify window uses has its MaintainsState property set to true since it uses a different extent than the Map's MapFunctionality object. To maintain state at the map functionality level, programmatically set the MapFunctionality MaintainsState property to true.
The following code example shows this point:
[C#] 
public MapView MapView
{
    get
    {
        if (maintainsState)
        {
            return mapView;
        }
        else
        {
            return MapResource.MapView;
        }
    }
}
The preceding code example shows how the ArcIMS MapFunctionality implementation for the MapView property works. If MaintainsState is true, it returns a local MapView instance. However, if it does not maintain its own state, it returns the MapView exposed by the resource.

ImageMapFunctionality and IMapFunctionality

ImageMapFunctionality is only implemented for ArcGIS for Server data sources that host image services. ArcGIS for Server image services host raster data and generate dynamic map images. ImageMapFunctionality implements some of the members defined by IMapFunctionality. In most cases, ImageMapFunctionality is used to gain access to ImageResource, which contains information about the image service, such as band names, IDs, and the image resource definition. The definition contains a reference to GeoImageDescription, an ArcGIS Server SOAP value object type that contains detailed information about the properties of the map image requested from the service. GeoImageDescription is defined at design time as part of a map resource item or modified at run time via the ImageResource.ImageResourceDefintion property.
The resource definition string for an image resource item (image service) is formatted as shown in the following code example:
[JavaScript] 
{
    "type": "ImageServer", "service": "<service name>", "imageDescription": {
        "bandIds": "<band ids>", "compressionQuality":  < compression quality > 
    }
}
The JavaScript Object Notation (JSON) formatted string consists of the following name-value pairs:
  • Type
  • Service
  • ImageDescription
You can add properties to the imageDescription array of values to modify the dynamic map image generated by the image service. Compression, noData, interpolation, and pixelType are supported. The properties reflect the GeoImageDescription created to generate a new map image. For example, define a NoData value equal to 89 to render pixels with a data value of 89 as transparent as shown in the following code example:
[JavaScript] 
{
    "type": "ImageServer", "service": "MyImageService", "imageDescription": {
        "bandIds": "0", "compressionQuality": 0, "noData": 89
    }
}

QueryFunctionality and IQueryFunctionality

QueryFunctionality is implemented for data sources that perform spatial and attribute queries on feature data. You can explicitly create a QueryFunctionality using the MapResource.CreateFunctionality() method. In most cases, you can work with the Common API reference, IQueryFunctionality, instead of explicitly casting to a data source implementation type.
The following table lists methods of IQueryFunctionality:
Method
Description
Find()
Searches the attributes of one or more layers in a map resource for the occurrence of a value. Returns a DataTable array.
GetFields()
Returns an array of field names in a layer within a map resource.
GetQueryableLayers()
Returns an array of layer names and IDs in a map resource that contains feature data and can be queried.
Identify()
Performs a spatial query on one or more layers in a map resource. The spatial component of the query consists of a geometry object and tolerance (or buffer) around the geometry. Returns a DataTable array. How tolerance is used depends on the type of data source. For additional information, see the ADF .NET library reference.
Query()
Performs a spatial or attribute query on one layer in a map resource. Returns a DataTable.
Supports()
Determines if an operation is supported by the functionality. The operation is the name of a member (property or method) on the functionality. For example, to check if the Identify() method is supported, pass the Identify string as the operation to the Supports() method. True is returned if the operation is supported, and false is returned if it is unsupported.
GetFields and GetQueryableLayers are used to obtain information about the map resource that can be used in a subsequent query. The System.Data.DataTable returned from Identify, Query, or Supports is a standard ADO.NET data object. If Web ADF geometry is returned from a query, it can be used as a Web ADF graphics layer in a graphics resource. The DataTable can also be used to display tabular data in a GridView.
The following code example shows how to iterate through the map resources in a map (Map1), query each queryable layer, and add the DataTable returned to a System.Data.Dataset for future use:
[C#] 
System.Data.DataSet dataset = new System.Data.DataSet();
IEnumerable func_enum = Map1.GetFunctionalities();
foreach (ESRI.ArcGIS.ADF.Web.DataSources.IGISFunctionality gisfunctionality in
    func_enum)
{
    ESRI.ArcGIS.ADF.Web.DataSources.IGISResource gisresource =
        gisfunctionality.Resource;
    bool supported = gisresource.SupportsFunctionality(typeof
        (ESRI.ArcGIS.ADF.Web.DataSources.IQueryFunctionality));
    if (supported)
    {
        ESRI.ArcGIS.ADF.Web.DataSources.IQueryFunctionality qfunc;
        qfunc = (ESRI.ArcGIS.ADF.Web.DataSources.IQueryFunctionality)
            gisresource.CreateFunctionality(typeof
            (ESRI.ArcGIS.ADF.Web.DataSources.IQueryFunctionality), null);
        string[] lids;
        string[] lnames;
        qfunc.GetQueryableLayers(null, out lids, out lnames);
        ESRI.ArcGIS.ADF.Web.Geometry.Envelope env = new
            ESRI.ArcGIS.ADF.Web.Geometry.Envelope( - 120, 30,  - 100, 40);
        ESRI.ArcGIS.ADF.Web.SpatialFilter spatialfilter = new
            ESRI.ArcGIS.ADF.Web.SpatialFilter();
        spatialfilter.Geometry = env;
        spatialfilter.ReturnADFGeometries = true;
        spatialfilter.MaxRecords = 1000;
        for (int i = 0; i < lids.Length; i++)
        {
            System.Data.DataTable dtable = qfunc.Query(null, lids[i], spatialfilter);
            dtable.TableName = gisresource.Name + "_" + lnames[i];
            dataset.Tables.Add(dtable);
        }
    }
}
Note the following regarding the preceding code example:
  • No data source-specific classes are used, only Common API interfaces. This is an example of working with the Common API in a data source agnostic manner.
  • The IGISResource.SupportsFunctionality() method determines if a map resource supports the query of layers by checking whether it supports IQueryFunctionality.
  • The IGISResource.CreateFunctionality() method creates an instance of a QueryFunctionality. Although it is an implementation type, the Web ADF can still use the IQueryFunctionality generic interface.
  • The Web ADF maintains its own set of classes to support queries using the Common API. ESRI.ArcGIS.ADF.Web.SpatialFilter and QueryFilter can both be used to define queries using the Query() method. The ReturnADFGeometries property determines if the DataTable returned from a query contains Web ADF geometry. To use the DataTable as a Web ADF graphics layer, this property needs to be set to true.
  • When an IQueryFunctionality method requires a map functionality name, a null value can be used. In this case, the resource used to create the query functionality is already associated with the IQueryFunctionality instance.
For more information on working with DataTables and Web ADF graphics layers, see the previously mentioned topic, Working with graphics and Converting between data types.

MapTocFunctionality and IMapTocFunctionality

MapTocFunctionality provides access to TOC data frames representing resources in a Toc control. Each resource has one TocDataFrame that contains one TocLayer for each layer in a resource. To change visibility of a layer in the TOC, use the GetLayerVisibility() or SetLayerVisibility() method on MapFunctionality. You might also need to refresh the Toc control after a visibility change. For an example, see the How to use MapFunctionality to change layer visibility.

TileFunctionality and ITileFunctionality

TileFunctionality enables a map to retrieve a pregenerated map image tile instead of requiring a new map image be generated (MapFunctionality). Of the out-of-the-box data sources supported by the Web ADF, only ArcGIS for Server and Bing Maps data sources support and implement the ITileFunctionality interface. ArcGIS for Server services can generate and provide map caches on the server. Bing Maps imagery is only provided a cache of map tiles.
In most cases, the only time you will work with ITileFunctionality is during the implementation of a custom data source that provides static map image tiles. For more information, see Creating custom data sources.

ScaleBarFunctionality and IScalebarFunctionality

ScaleBarFunctionality exposes the ability of a map resource to generate a scale bar image for use in an application. The ScaleBar control uses IScalebarFunctionality to generate content.


See Also:

Resources and functionalities in the Web ADF
Data source-specific APIs
Geocode resources
Geoprocessing resources