MapResourceManager control

The MapResourceManager control is often the first control you'll add to a Web application.  The design-time interface enables you to add, remove and set properties for any resource that provides mapped output, for example an ArcIMS image service or an ArcGIS Server map service.   Since the control is designed to manage multiple resources at the same time, it provides properties to define how the resources interact, such as the order of layers and transparency of map image output.   Multiple controls can use the same MapResourceManager to access the same set of resources.   As a result, changes to a resource can be reflected in any control associated with the same MapResourceManager. 
   
Assembly: ESRI.ArcGIS.ADF.Web.UI.WebControls.dll
Class: ESRI.ArcGIS.ADF.Web.UI.WebControls.MapResourceManager
JavaScript libraries: display_common.js, display_dotnetadf.js

Using the MapResourceManager control

1. Add the control to the page
   
   Open or create a Web site within Visual Studio.NET.   Open a Web form in design mode, select the Toolbox and expand the ArcGIS Web Controls tab.  Drag and drop a MapResourceManager control on the Web form.  You should see the following in Visual Studio.NET:  
   
   
   
   Note that the MapResourceManager is only visible at design-time. 
2. Add resources
   
   To add map resources for use within your Web application, activate the control, open or navigate to the Properties window and click the ellipsis (...) next to the ResourceItems property.  A resource collection editor dialog should be displayed.
   
   
   
   
   On the MapResourceItem Collection Editor dialog, click the Add button to add a data source as a map resource to the MapResourceManager control.   A MapResourceItem is added to the collection.  This item provides a couple of properties to modify how the data source associated with this map resource is displayed by other controls in the Web applications, such as a Map or Toc. 
   
   
   
   
   The Name property is used to uniquely identify the resource within the web application. This name will appear in the Toc control (table of contents) as the name of the map service at the top of the Toc hierarchy. It is highly recommended to set the resource name to a descriptive value in your application. Often a good choice will be the name of the map service.
   
   Under Appearance, the Display Settings  property opens a Map Resource Display Settings Editor, which is used to define the content of a map image generated by a data source. If a map image is created, transparent color and background work together define a color that will be rendered transparent in a map image. 
   
   Blending  the resource defines the visibility of a map image relative to other map images in the same map resource collection.   When more than one map resource is visible, the map images generated by each data source are blended together into a single image.  The map resource at the bottom of the list is drawn first; the one above it is drawn next and so on.  Transparency values are defined for the entire map image.  A value of 0% means the map image will not be transparent.  A value of 100% means the map image will be completely transparent, thus not visible.  A value between 0% and 100% will render the contents of a map image, permitting the display of the contents in map images below it.  If an image is partially transparent, it may take longer to generate a consolidated map image including all map resources.  
   
   The Request MIME Data option determines how the map image will be requested from the data source.  If the data source supports sending a map image via MIME format, the image will be stored in-memory by the Web ADF application.  If MIME data is not supported or selected, a data source must generate an output image file and share the file location with the Web ADF application.  Image format defines the type of image generated by a data source, for example, the format of the image generated by ArcGIS Server container process or the ArcIMS spatial server. 
   
   Visible determines if a map image is generated.  If a Toc is buddied to a Map control, the layer will be checked on in the Toc if Visible is checked here. If Visible is not checked, the layer will be unchecked in the Toc. 
   
   The Display in the Table of Contents property allows you to hide a resource in the table of contents (Toc control).  The resource can still be visible in the Map or OverviewMap controls and utilized by other controls, such as the SearchAttributesTask.
    
   On the MapResourceItem Collection Editor dialog, the Definition property provides a set of dialogs to connect to a data source provider (i.e. GIS Server) and create a map resource.  Click the ellipsis (...) for the Definition property to open the Resource Definition Editor.  Select the type of data source and define the appropriate properties (see dialogs below).   The following data source types are available:
   
   
   ArcGIS Server Local
   
   Connecting to an ArcGIS Server Local data source requires the machine name, or connection host, on which the Server Object Manager is running.  The Additional GIS Servers button enables configuring fail-over/round-robin connections for the resource.  See the section Using the Connection Library for more details. 
   
   Once the data source is defined, the Resource property opens the ArcGIS Resource Definition Editor dialog which provides a list of available map services and data frames.         
   
   
   
                                                      
                    
   
   
   Note that the Identity property is grayed out and cannot be set from the Map Resource Definition Editor dialog.  At design-time, the identity of the user running Visual Studio is used to connect to an ArcGIS Server local data source.  At runtime, that identity is established by the Web application.  Only one identity can be used to define access to all ArcGIS Server local data sources in a single Web application.  You can define this identity by right-clicking the Web project in Solution Explorer and selecting the Add ArcGIS Identity option.  Enter the identity credentials which will be used to access ArcGIS Server local resources at runtime.  This information will be added to the web.config file within a standard ASP.NET identity tag.  If the "Encrypt identity in web.config" checkbox is checked, the identity tag will be encrypted; otherwise, the username and password will be stored as clear text.    
   
   
   
   
   
   
   
   ArcGIS Server Internet
   
   ArcGIS Server Web Services require entering the partial URL to the ArcGIS Manager collection of services.  This URL includes the Web server host name, ArcGIS instance, and "services" folder name.  This general URL will provide a list of ArcGIS Server Web Services to choose from. 
   
   If authentication is enabled for the ArcGIS Server Web service, you will need to provide a username and password.  ArcGIS Server Web services are designed to support Basic, Digest, and Integrated authentication.  Basic and Digest authentication options can be used to secure ArcGIS Server Web services provided on the Internet.   All options can be used to secure ArcGIS Server Web services on a local area network.    Since Basic and Digest options can be insecure, confirm that the Web site on which ArcGIS Server Web services are available provides a secure channel for communication - namely, that it has enabled SSL encryption accessible via HTTPS.  This will sufficiently encrypt the transmission of identity credentials for both authentication options.    
   
   Once the data source and identity (if necessary) are entered, the Resource property opens the ArcGIS Resource Definition Editor dialog which provides a list of available map services and data frames.  The identity will determine which services are available.  If no identity is specified, the remote Web server is responsible for assigning an identity, often an anonymous user account.  
   
   
   
                                                      
                      
                                                      
                     
                     
   Ensure that ArcGIS Internet data sources you use are pooled GIS services. Pooled services are shared among users of the Web application. Non-pooled service instances (processes) are dedicated to a single user, and the instance is destroyed after the user finishes with it. If you use a non-pooled service in an Internet connection, a new process will be created and destroyed with every map or other GIS operation. This will lead to inefficient use of resources on the GIS server, and will contribute no advantage to the application. If necessary, contact the GIS server administrator to ensure that Internet services used in the application are set to pooled status. For more information on pooling of services, see Tuning and configuring services in ArcGIS Server Help.
   
   ArcIMS
   
   Two options are available for connecting to an ArcIMS data source:
   
   TCP :  If the Web ADF application has direct network access to the ArcIMS Application Server, you can create a TCP connection.  Specify the hostname of the machine on which the ArcIMS Application Server is running and the connection port (default 5300).  TCP connections do not use authentication, therefore the Identity credentials are not used. 
   
   HTTP:  If the Web ADF application has access to a Web server that exposes the ArcIMS Servlet Connector you can use an HTTP connection.   Specify the Web server hostname and the Web ADF will discover if an appropriate endpoint is available. You can alternatively specify the full path to the endpoint.  By default, the Servlet Connector path is /servlet/com.esri.esrimap.Esrimap.  The ArcXMLHandler does not have a default location.  If authentication has been enabled, enter the appropriate information in the ArcIMS Identity Editor dialog.
   
   The Additional IMS Servers button enables configuring fail-over/round-robin connections for the resource.  See Using the Connection Library for more details.  
   
   Once the connection properties have been set, use the Resource Definition Editor dialog to select a map service.
   
   
                                                     
                    
                                                      
                    
   
   
   ArcWeb Services
   
   ArcWeb Services provide dynamic map content via the Map Image Web service, and query functionality via the Spatial Query Web service.   The URL for the Map Image Web service is preset (not visible in the dialog) and cannot be changed.  The Map Image Web service URL is: http://www.arcwebservices.com/services/v2006/MapImage.wsdl. 
   
   The URL for the Spatial Query Web service is also preset in the dialog and cannot be changed.  The Spatial Query Web service URL is:  
   http://www.arcwebservices.com/services/v2006/SpatialQuery.wsdl.   
   
   A valid ArcWeb account (ESRI Global user account) must be specified to connect to both ArcWeb services.   Once connected, the Resource Definition Editor dialog allows you to browse any ArcWeb services that generate map images via the Map drop-down list.  In addition, the Query drop-down list displays a list of data layers (provided as ArcWeb services) which can be used to query both feature geometry and attribute values.     
   
   
   
                                                     
                    
   
   
   OGC (WMS) Service
   
   The Open Geospatial Consortium's Web Map Service (WMS) specification allows for publishing of geographic data on the Web in a common way.   Any Web endpoint that adheres to WMS specifications can be consumed as a data source by the Web ADF.  Two common WMS endpoints are provided by ArcIMS and ArcGIS Server Web services.  The OGC (WMS) Data Source Definition Editor dialog allows you to define a URL to a WMS data source.   One map data source can be defined per URL.  The dialog displays the contents of the map data source upon successful connection.  Select a map layer to display its metadata in the dialog.  
   
   The common URL for an ArcIMS WMS service is:
   http://<hostname>/wmsconnector/com.esri.wms.Esrimap/<servicename>
   
   The common URL for an ArcGIS Server WMS service is:
   http://<hostname>/arcgis/services/<servicename>/MapServer/WMSServer
   
   Identity credentials are not required to work with OGC WMS Services.  In addition, since there can be only one resource per data source, a resource setting is not necessary.
   
   
       
   
   
   Graphics Layers
   
   Graphics layers provide the ability to draw geometry and text on a map without necessarily being associated with a data source.   By default, a Graphics layer does not have content.  Geometry and text梐s well as their symbols, renderers, and attributes梞ust be added programmatically. 
   
   
   
   
3. Specify buddy controls
   
   Add other Web ADF controls to the Web form and buddy them with the MapResourceManager.  In most cases, a Map control is buddied with a MapResourceManager by setting the Map's MapResourceManager property.   See the Map control topic for additional details.   

 

Members

Properties

  The following table provides a list of properties and events of interest.  For complete reference information, see the MapResourceManager control in the library reference section.

Property Name	Type	Description
Initialized	bool	Indicates if the resource manager has been initialized during the current postback.
ResourceItems	GISResourceItemCollection  <MapResourceItem>	Returns a collection of MapResourceItems.  Each MapResourceItem references a resource instance and display settings for the item.

Events

Event Type	Description
ResourceInit	Occurs when initializing a single resource.  More specifically, when the Initialize method is called with a parameter.
ResourcesDispose	Occurs when resources are disposed.  More specifically, when the Dispose method is called, usually at the end of the ASP.NET page lifecycle.  Occurs after the rendering phase in a full page postback and after GetCallbackResult in a callback.
ResourcesInit	Occurs when all resources are initialized.  More specifically, when the Initialize method is called without any parameters.

Discussion 
     

• Using Layer Definitions
  
  At times, it may be necessary to present only a subset of features in a feature layer for display.  Each map resource can contain many feature layers.  The Web ADF Common API does not provide a generic means to filter and subset layer content.   Rules for applying a definition to a layer within a map resource depend on the data source type.  Note, a layer definition will affect the display of features in the feature layer but will not restrict queries.  To restrict queries, either change the properties of the service or modify the Web ADF application to check query content before they are initiated.  
  
  If a feature layer definition must be applied for the entire user session, set the definition during the Page Load or MapResourceManager Load event.  Each data source is discussed below - a MapResourceManager named "MapResourceManager1" is assumed to be available in a Web page:
  
  [C#]

  void Page_Load(object sender, EventArgs e)
  {
      if (!IsPostBack)
      {						
          // set initial definition properties here			
      }
  }						

  • ArcGIS Server
    
    Both local and Internet data source types utilize the ArcGIS Server SOAP API, thus both can apply a definition to a feature layer using the LayerDescription.DefinitionExpression property.  The definition will be maintained in state by the Web ADF for the duration of the session.  The state of the server object will not be changed.  Use the following code as an example: 
    
    [C#]

    if (!MapResourceManager1.Initialized)
      MapResourceManager1.Initialize();
    
    ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceBase mrb = (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceBase)
        MapResourceManager1.GetResource(0);
        
    ESRI.ArcGIS.ADF.ArcGISServer.MapDescription mapdesc = mrb.MapDescription; 
    ESRI.ArcGIS.ADF.ArcGISServer.LayerDescription layerdesc = mapdesc.LayerDescriptions[0]; 
    layerdesc.DefinitionExpression = "OBJECTID IN (3,5)";							
    							

    When working with non-pooled map services, a stateful change to the server object is recommended.  This will guarantee that a layer definition will successfully limit both the display and query of layer features.   An ArcGIS Server local data source is required to make a stateful change to a server object.  Use the following example as a guide.  For a more detailed discussion on making stateful changes to a map service, see the ArcGIS Server section in the Access a data source specific API discussion.
    
    [C#]

    if (!MapResourceManager1.Initialized)
      MapResourceManager1.Initialize();								
    
    ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceLocal mrl = (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceLocal)
        MapResourceManager1.GetResource(0);
    
    IMapServer ms = (IMapServer)mrl.ServerContextInfo.ServerContext.ServerObject;
    IMapServerObjects2 mso = (IMapServerObjects2)ms;
    IMap map = mso.get_Map(ms.DefaultMapName);
    IFeatureLayer2 layer = (IFeatureLayer2)map.get_Layer(0);
    IFeatureLayerDefinition2 definition = (IFeatureLayerDefinition2)layer;
    definition.DefinitionExpression = "OBJECTID IN (3,5)";
    mrl.RefreshServerObjects();
    							

  • ArcIMS
    
    The ArcIMS API provides the classes and properties necessary to apply a layer definition to a feature layer in an ArcIMS service.  A Filter object can store the definition expression and be associated with a layer via the FeatureLayer.Filter property.  The definition will be maintained in state by the Web ADF for the duration of the session. Use the following code as an example:
    
    [C#]

    if (!MapResourceManager1.Initialized)
      MapResourceManager1.Initialize();	
      
    ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapResource mr = (ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapResource)
        MapResourceManager1.GetResource(0);
    ESRI.ArcGIS.ADF.IMS.Carto.MapView mapview = mr.MapView;
    
    ESRI.ArcGIS.ADF.IMS.Carto.Layer.FeatureLayer featurelayer = (ESRI.ArcGIS.ADF.IMS.Carto.Layer.FeatureLayer)mapview.Layers[0];
    ESRI.ArcGIS.ADF.IMS.Carto.Layer.Filter filter = new ESRI.ArcGIS.ADF.IMS.Carto.Layer.Filter("#ID# < 10");
    featurelayer.Filter = filter;
    							

  • ArcWeb and OGC/WMS
    
    Layer definitions are not available.
    
            
• Using multiple MapResourceManagers
  
  If you are adding multiple MapResourceManager controls to a single page, set the map resource item names to be unique across all MapResourceManager controls in the page. This will prevent any confusion at runtime between resources with identical names.