GeocodeResourceManager control

The GeocodeResourceManager control allows a developer to add, remove, and set properties for any data source that provides geocoding capabilities. ArcGIS Server, ArcIMS, Microsoft Virtual Earth and ArcWeb data sources can be utilized.  The FindAddressTask control is designed to use the resources provided by the GeocodeResourceManager to geocode address or variable (e.g. place name or landmark) inputs.   In addition, the IGeocodeResource and IGeocodeFunctionality interfaces in the Common API enable a developer to work with a geocode service programmatically.   

Assembly: ESRI.ArcGIS.ADF.Web.UI.WebControls.dll
Class: ESRI.ArcGIS.ADF.Web.UI.WebControls.GeocodeResourceManager
 

Using the GeocodeResourceManager 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 GeocodeResourceManager on the Web form.  You should see the following in Visual Studio.NET:
   
     
   
   Note that the GeocodeResourceManager is only visible at design-time.
2. Add a resource item
   
   To add geocode 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 GeocodeResourceItem Collection Editor dialog, click the Add button to add a data source as a geocode resource to the GeocodeResourceManager control.   A GeocodeResourceItem is added to the collection.  This item provides properties to modify the behavior of the resource, such as minimum candidate score, minimum match score, and whether to return just match candidates or all candidates.   Candidate and match scores for an address are determined by the geocode service, not the Web ADF.   Each data source utilizes different, although related, methods for managing geocode parameters to calculate scores. 
   
   The following properties can be modified for a geocode resource item in the collection editor dialog:
   1. Name
      
      The Name property is used to uniquely identify the resource within the web application.  It is highly recommended to set the resource name to a descriptive value in your application. 
   2. MinCandidateScore
      
      MinCandidateScore is a value between 0-100.  When a geocode service searches for likely candidates in the reference data, it uses this threshold to filter the results provided.  Locations that yield a score lower than this threshold are not returned.  If the geocode service seems unable to find any candidates for an address that you want to geocode, you can lower this setting so candidates with lower scores are returned. By default, this value is set to the value defined by the service.
   3. MinMatchScore
      
      MinMatchScore is a value between 0-100.  The minimum match score lets you control how closely addresses have to match their most likely candidate in the reference data to be considered a match for the address. A perfect match yields a score of 100.  A match score between 80 and 99 can generally be considered a good match.  An address below the minimum match score is considered to have no match, but may still be a candidate depending on the MinCandidateScore value. By default, this value is defined by the service. If your application demands that addresses be located with a high level of confidence, you should set a higher minimum match score. If you want to maximize the number of addresses that can be matched and don't mind if some addresses are potentially matched incorrectly, you can use a lower setting.  
   4. ShowAllCandidates
      
      ShowAllCandidates can be true or false.  If true, all candidates which have a score greater than the MinCandidateScore are returned.  If false, only candidates with a score greater than the MinMatchScore  are returned.  By default, the value is false.
   5. Definition
      
      On the GeocodeResourceItem Collection Editor dialog, the Definition property provides a set of dialogs to connect to a data source provider and create a geocode 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 geocode service 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 (connection host) on which the Server Object Manager is running.  The Additional GIS Servers button enables configuring a fail-over or round-robin connection for the resource.  See Using the Connection Library section 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 geocode services. 
      
      
                                                    
                        
      
      
      Note that the Identity property is grayed out and cannot be set from the 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.  This identity can be explicitly defined when building the Web ADF application in Visual Studio by right-clicking the Web project in Solution Explorer, and selecting the Add ArcGIS Identity option.  Enter the identity credentials that 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 provides a list of ArcGIS Server Web Services to choose from. 
      
      If authentication is enabled for an ArcGIS Server Web service, you must provide a username and password to gain access to the Web services.  ArcGIS Server Web services are designed to use Basic authentication, therefore username and password are Base64 encoded and included in the HTTP request to the Web server.  Since this is inherently insecure, confirm that your Web site provides a secure channel for communication - namely it has enabled SSL encryption accessible via HTTPS.  This will sufficiently encrypt the transmission of identity credentials for Basic authentication.       
      
      Once the data source and identity are entered, the Resource property provides a list of available geocode services.  The identity determines which services are available.  If no identity is specified, the remote Web server is responsible for assigning an identity, often an anonymous user account.  
      
      
      
                                                         
                         
                                                         
                        
      
                                                       
                        
      ArcIMS
      
      ArcIMS has two options for connecting to services:
      
      TCP :  If the Web ADF application has direct 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 create an HTTP connection.   Specify the Web server hostname and the Web ADF will discover if an appropriate endpoint is available. You can also specify a full path to the endpoint.  By default, the Servlet Connector path is /servlet/com.esri.esrimap.Esrimap .  If authentication has been enabled, enter the appropriate information in the ArcIMS Identity Editor dialog.
      
      The Additional IMS Servers button enables configuring a fail-over or round-robin connection 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 an Image Service that has geocoding enabled.  To enable geocoding on an ArcIMS Image Service, at least one layer in the service must be configured for geocoding. For more information, see the ArcXML Programmer's Reference Guide. Once the service is selected, pick the layer in the service which will be utilized in the Web ADF as a geocode resource.
      
      
      
                                                        
                       
                                                         
                       
      
      
      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 location-based services that utilize a variety of data sources for different regions of the world.   The URL for the ArcWeb Web service that provides geocode capabilities is preset and cannot be changed.  The Web service URL is: http://www.arcwebservices.com/services/v2006/AddressFinder.wsdl. 
      
      A valid ArcWeb account must be specified to connect to ArcWeb services.   Once connected, the Resource Definition Editor dialog allows you to browse any ArcWeb services that provide geocoding services. 
      
      
      
                                                        
                       
      
      
      Microsoft Bing Maps (formerly known as Virtual Earth)
      
      The Microsoft Live Services SDK hosts a Bing Maps geocode Web service for address and place matching.  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. 
      
      Since there is only one Bing Maps geocode Web service, the Resource Definition Editor only enables you to select between the staging and production environments.  If you have not recieved a license to use the Bing Maps production environment, check the "Use staging server" box.
      
      
                                   
      
      
      
      
3. Specify buddy controls
   
   To utilize the resources in the GeocodeResourceManager, add a FindAddressTask control.  The FindAddressTask task control can only work with one geocode resource at a time.  You can also utilize geocode resources programmatically via geocode functionalities.  Composite geocoding is also possible using the Web ADF, but it requires custom programming.   Composite geocoding combines and utilizes a set of geocoding services for a single address matching process.  The geocoding services are assigned a priority where if the first service (highest priority) does not provide an adequate match, the next service is used.  The process continues until a successful match is returned or all geocode services are unable return a candidate.         
   

Members

Properties

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

Property Name	Type	Description
ResourceItems	GISResourceItemCollection	The GeocodeResourceItem collection managed by this control.

Discussion  

• Initialize a geocode resource programmatically
  
  A geocode resource will be initialized for you if working with a FindAddress task control.  However, if you are working with a geocode resource outside of the FindAddress task you may need to initialize it before it can be used.  The same situation applies when creating a GeocodeResourceManager and adding geocode resources dynamically at runtime.  Specifically, the GeocodeResource needs to be initialized.  The resource manager is responsible for managing the data source connection, thus server context creation and disposal are managed for you.  The following example illustrates how to retrieve a geocode resource item from a GeocodeResourceManager, initialize the resource and create a geocode functionality to use for address matching operations.    
  
  [C#]

  GeocodeResourceItem geocodeResourceItem = GeocodeResourceManager1.ResourceItems.Find("Geocode Resource");
  
  if (!geocodeResourceItem.Resource.Initialized)
      geocodeResourceItem.InitializeResource();
  
  // Create a Web ADF Common API geocode functionality
  IGeocodeFunctionality commonGeocodeFunctionality = (IGeocodeFunctionality)
    (geocodeResourceItem.Resource.CreateFunctionality(typeof(IGeocodeFunctionality), null));