The GeocodeResourceManager control allows a developer to add, remove, and set properties for any data source that provides geocoding capabilities. ArcGIS Server, ArcIMS, and ArcWeb data sources can be utilized.  The FindAddressTask control is designed to use the resources provided by the GeocodeResourceManager to geocode address 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
JavaScript libraries: display_common.js, display_dotnetadf.js
 

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 resources
   
   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. 
   
   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 10. 
   
   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 setting is 60. 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.  
   
   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.
   
   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 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 or the Web ADF ArcXMLHandler, 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.  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 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
   
   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. 
   
   
   
                                                     
                    
   
   
3. Specify buddy controls
   
   To utilize the resources in the GeocodeResouceManager, 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 (see sample code below).  The resource manager is responsible for managing the data source connection, thus server context creation and disposal are managed for you.     
  
  [C#]

  GeocodeResourceManager geocodeResourceManager = new GeocodeResourceManager();
  
  GeocodeResourceItem geocodeResourceItem = new GeocodeResourceItem();
  geocodeResourceItem.Name = "GeocodeResourceItem";
  
  GISResourceItemDefinition definition = new GISResourceItemDefinition();
  
  definition.DataSourceDefinition = "localhost";
  definition.DataSourceType = "ArcGIS Server Local";
  definition.ResourceDefinition = "PortlandGeocode";
  
  geocodeResourceItem.Definition = definition;
  
  geocodeResourceManager.ResourceItems.Add(geocodeResourceItem);
  geocodeResourceManager.CreateResource(geocodeResourceItem);
  
  IGISResource gisResource = geocodeResourceManager.GetResource(0);
  
  if (!gisResource.Initialized)
      geocodeResourceItem.InitializeResource();