Developing Web Applications with the Web ADF - Web controls  

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 ArcGIS Server map or image 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

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 following properties can be modified for a map resource item in the resource collection editor dialog:

    1. Name

      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 or data frame (if applicable).

    2. DisplaySettings

      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. 
       
      The Transparency Settings section includes a set of options to define the visibility of a map image generated by a map resource 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.  How they are blended depends on the ImageBlendingMode property setting on a Map control.   The map resource at the bottom of the list is drawn first; the one above it is drawn next and so on.  A single color in the map image generated by a map resource can be rendered completely transparent.   Use the color picker to select the color and check the "Make background transparent" check box.  In many cases the background color of a map image is set to transparent since it often references empty space.   The background color of a map image is dependent on settings in the map service configuration file (e.g. *.mxd).  The background color for Web ADF Graphics Layer map resources is always transparent. 

      You also have the option of defining variable transparency 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 and permit viewing contents in map images below it.    


      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.


      Image Format defines the type of image a map resource should generate.  The image type is especially important if you need some level of transparency.  PNG, GIF and BMP image types support transparency whereas JPG do not.  Note, to display semi-transparent symbology in Web ADF graphics layers, set the Image Format to PNG32 for graphics map resource items. 

      The picklist of image formats is static and some formats may not be available depending on the type of service you are using (MXD-based ArcGIS Server, MSD-based ArcGIS Server, ArcIMS, etc.). If you select an image format that the service does not support, the server will revert to its default image format.For example, if you're using an MSD-based service with antialiasing, you should choose the PNG 32 image format to get the best visual quality. In contrast, PNG32 is not available with MXD-based services. If you choose PNG32 with an MXD-based service, the server will revert to the default of PNG24.

      Dynamic Tiling applies to map resources that generate dynamic map images (not map resources associated with a cached service).   

      When Enabled, a resource-specific tiling scheme is constructed.  The tiling scheme generates a grid with a cell size based on the current map control size.  Each cell defines the bounds of a map image which will be generated if the map view overlaps its extent.  As long as the map scale remains the same, the grid remains valid.  As map image are retreived, they are maintained in browser memory and reused.  When the scale changes the tiling scheme is reset and a new grid is defined.   This option enhances end user interaction with a Web ADF Map control, but requires that the map service on which the resource is based is able to generate map images in a timely manner.   It is possible that up to 3 dynamic map images will be request as the result of an extent change.

      When Disabled, no tiling scheme is constructed for a map resource and each extent change generates a new dynamic map image.   Only one map image per dynamic map resource is requested at a time.  

      When Default, the data source type defines whether dynamic tiling is enabled or disabled.  Here are the default values:

      Data Source Type Dynamic Tiling Default
      ArcGIS Server Local Disabled
      ArcGIS Server Internet Disabled
      ArcIMS Enabled
      ArcWeb Disabled
      OGC\WMS Disabled
      Graphics Enabled
      Microsoft Virtual Earth Not applicable (no dynamic map services provided)

    3. Definition

      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 Data Source property may be a url to an ArcGIS Server service catalog or local machine name and optional connection port.  Some data sources support authentication.  The Identity property enables you to define the appropriate runtime credentials to connect to the data source and utilize the resource.  The Resource property defines the map service and, if supported by the data source, the subparts (e.g. map and layers) to use when working with the resource.   The format of each property string is defined by the type of data source. 

      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 and image services.   The icon next to a service indicates the service type: map or image.  If a map service is selected, the properties portion of the dialog enables the selection of the active data frame.  If an image service is selected, the properties portion of the dialog enables you to change the compression quality and the bands rendered in the output image.                  



                                                         
                       


      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 and image services.  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.  The icon next to a service indicates the service type: map or image.  If a map service is selected, the properties portion of the dialog enables the selection of the active data frame.  If an image service is selected, the properties portion of the dialog enables you to change the compression quality and the bands rendered in the output image.  


                                                         
                         
                                                         
                        
                        

      The resource definition string for a map resource item (map service) is formatted as follows: 
      <layer id>@<data frame name>@<service name>
      By default the layer id portion of the string is not included.  You can insert a layer id in the resource definition string to define a single layer in the service you want to be accessible (e.g. drawn in the map). 

      To use the default data frame specify the value "(default)" for the data frame name portion of the definition. 


      The resource definition string for an image resource item (image service) is formatted as follows: 
      {"type":"ImageServer","service":"<service name>","imageDescription":{"bandIds":"<band ids>",
      "compressionQuality":<compression quality>}}
      The JSON formatted string consists of three name-value pairs: type, service, and imageDescription.  The service name, band ids and compression quality properties are updated via the Resource Definition Editor dialog.  In the dialog, you can add properties to the imageDescription array of values to modify the dynamic map image generated by the image service.  Only 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.
        {"type":"ImageServer","service":"MyImageService","imageDescription":{"bandIds":"0",
      "compressionQuality":0, "noData":89}}
       
      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

      * Note, the ArcWeb service data source has been deprecated in ArcGIS Server 9.3.1.  This data source will be removed in the next minor version release.

      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. 

          


      You can further define a subset of layers you want to include in the map using the resource definition string.   By default, the resource definition string is empty.  To modify it, view the page markup that contains the WMS map resource item.   Navigate to the ResourceDefinition argument in the Definition string.   Add the "layerSubset" argument and define a comma-delimited list of layer names to include with the resource item.   Here is an example:
      ResourceDefinition=&quot;layerSubset=3,6,12&quot;
      	
      To optimize performance only the first 10 layers in the service will be visible in the map.   You can override the number of visible layers programatically on the WMS map resource.  

      [C#]
      protected void Page_Init(object sender, EventArgs e)
          {
              IMapResource mapResource = MapResourceManager1.GetResource("MapResourceItem0");
              if (mapResource != null)
              {
                  ESRI.ArcGIS.ADF.Web.DataSources.OGCWMSService.MapResource wmsMapResource =
                        mapResource as ESRI.ArcGIS.ADF.Web.DataSources.OGCWMSService.MapResource;
                  if (wmsMapResource != null)
                  {
                      wmsMapResource.MaxInitialSelectedLayers = 2;
                      wmsMapResource.DisplayErrorAsImage = true;
                  }
              }
          }
          
      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—as well as their symbols, renderers, and attributes—must be added programmatically.  Note, to display semi-transparent symbology in Web ADF graphics layers, set the Image Format to PNG32 in the Display Settings for the graphics map resource item. 




      Microsoft Bing Maps (formerly known as Virtual Earth)

      The Microsoft Live Services SDK hosts Bing Maps Web Services which provide access to a set of cached roads and aerial map imagery.  Bing Maps maintains two service environments: staging and production.  The staging environment is designed to support development and testing use of Bing Maps services; they are free of charge.  The production environment offers optimized services designed to support deployed applications; it requires a license fee.   In either case, you will need a Bing Maps account id.  See the Virtual Earth data source discussion for steps on how to get existing account information or create an account.

      When adding a Microsoft Virtual Earth resource item, you must provide the account id and password in the Identity Editor. 

      The Resource Definition Editor enables you to select the map style: Roads, Aerial, or Aerial with labels.  The Roads style contains detailed roads and landmarks.  Aerial contains aerial imagery and Aerial with labels adds landmark labels to aerial imagery.  Label culture defines the language of the labels when Aerial with labels style is used.  Note, Bing Maps imagery is only provided in the Web Mercator coordinate system and cannot be reprojected on the fly.  If you have not recieved a license to use the Bing Maps production environment, check the "Use staging server" box.



                                     

              

    4. LayerDefinitions

      The LayerDefinitions property enables you to define a format for the rendering and attribute display of query results associated with each feature layer in the map resource.  It is important to note, creating a definition for a layer does not change the rendering of a layer in the map, it is only used for displaying results from the layer (e.g. querying the layer).   Results are displayed using Web ADF graphics.  Web ADF graphics provide enhanced client-side interactivity, in this case it offers the ability to highlight the feature under the mouse cursor, display MapTips on points, lines, and polygons, and customize attribute display in a MapTip callout box.   Two Web ADF task controls, Search Attributes Task and Query Attributes Task, are designed to use LayerDefinitions to display results.   

      The Layer Properties dialog provides a table of contents to select each feature layer in a map resource, and a tabbed window to define the symbology, field display, and record format for the selected layer.   When finished configuring layer properties, click the Apply button to define these properties as part of the map resource item.

          


      Symbols

      The Symbols tab enables you to define the default and highlight symbol for results generated using the selected layer.   Click on the button next to "Draw with:" or "Highlight with:" to change the symbol.   When results are generated from the selected layer at runtime, features will be rendered in the browser using the default ("Draw with:") symbol.   When the mouse cursor hovers over a feature, the highlight symbol ("Highlight with:") will display.  The feature type of the layer will determine the options for changing the symbol.   

      Point feature layers will display a dialog containing marker symbols.  Select the symbol (note the selected symbol is displayed in the bottom left corner of the dialog).   You can modify the marker symbols displayed in the dialog by adding\removing items in the xml formatted "usersymbols.config" file in the <IISROOT>/aspnet_client/ESRI/WebADF/MarkerSymbols folder.   Open the "usersymbols.config" file in your favorite text editor and use the description in the header of the file to define the appropriate format for adding items.    The same folder contains a "symbols.config" file with references to default marker symbols included with the Web ADF.  The "symbols.config" file should not be edited since it may be subject to change in future releases.   
         
       

      Line feature layers will display a dialog to change the color, width, and transparency of the symbol.  Click on the color box to display a color picker.  Colors can be defined using Red, Green, Blue or Hue, Saturation, Luminence combinations.  Transparency values range from completely transparent (0) to opaque (100).

       

      Polygon feature layers will display a dialog to change the boundary color, width, and transparency as well as the fill color and transparency.  Click on the color box to display a color picker.  Colors can be defined using Red, Green, Blue or Hue, Saturation, Luminence combinations. Transparency values range from completely transparent (0) to opaque (100).  

       

       
      Fields

      The Fields tab displays the fields in the selected layer.   The check box next to each field can be used to set the field visibility.   You can also edit the text in the Alias field if you do not want to use the original field name.  

      The primary display field is often used to describe the contents of a record.  In general, it is set to a field that contains an intuitive, preferrably unique value to identify an attribute.  You can select the primary display field using the drop down box next to "Primary display field".  

      The default values in the Fields tab reflect the field aliases, visibility and primary display field that you set in the configuration file ( e.g. map document -.mxd) for the map service.    The values entered in this dialog will only override these settings in the current Web application.   If you want the fields to appear the same way in multiple Web applications, consider setting the field properties in the map service configuration file instead of resetting them in each Web application.



      Results generated from querying the selected layer will contain only visible fields and use field aliases to define column names.  The primary display field will be used to define the parent node text for attributes displayed in a TaskResults control.      

      For data sources that do not provide field settings, all fields are visible by default and the alias is the same as the field name. The primary display field is set to the first string field with "name" in it.   If no such field is found, the first string field is used.   If there are no string fields, the first numeric field is used.

      Records

      The Records tab displays the tabular format of results as displayed within the browser at runtime.  Record display properties for a specific layer can be used to display results within a TaskResults control or in a MapTips callout window.  By default, visible fields are included in the record display as name value pairs and the title is the primary display field.  



      To customize the look and feel of record display, select the Custom Formatting radio button.  The Title and Contents sections of the dialog are now editable.  The Contents section provides a rich text editor to modify font style and color or add fields, hyperlinks, tables or images.  Edits are stored as HTML style content to be rendered in the browser at runtime.



      To view the HTML content that will be used to format layer results, select the HTML radio button at the bottom of the dialog.  The raw HTML content will be displayed in the Content window.  Any valid content to be rendered in a browser can be added - this includes HTML, CSS definitions, and JavaScript. 



      If a task, such as the SearchAttributesTask, uses the default layer format for a queryable layer, the layer format defined with the layer's map resource item will be used to render results at runtime.   The following example shows the results for a search on the Cities layer using the SearchAttributesTask.  The results are displayed in a TaskResults control. 

       

  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