Using the Connection library

In this topic

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

About the Connection library

The Connection library is a .NET assembly (ESRI.ArcGIS.ADF.Connection.Core.dll) included with the Web Application Developer Framework (ADF) and other Esri developer products. It provides Microsoft .NET developers with a single library for connecting to ArcGIS for Server locally via the server object manager (SOM), and ArcIMS via Hypertext Transfer Protocol (HTTP) and Transmission Control Protocol (TCP). The Connection library also contains a ConnectionManager to configure failover and round-robin capabilities in a custom application. 

Working with the ConnectionManager

The Connection library includes a ConnectionManager to enhance the capabilities of an application by providing techniques to create a fail safe and high performance solution. You can group a collection of connections to handle application requests for a resource. In this case, the application only needs access to the resource. The ConnectionManager determines which server is used to retrieve the data. See the following options:
  • Failover—Ensures that service requests are always channeled to a working connection and server. All requests are sent to a primary server, unless it is unavailable or a request fails, then a secondary server is used.
  • Round-robin—Makes efficient use of the available servers to handle high request volumes. Both primary and secondary servers are used to service requests. Servers are used in sequence, with the first request sent to the primary server, the second request to the secondary server, and so on.
ConnectionManager capabilities can be utilized in the following ways:
  • Using the Web ADF resource manager dialog boxes to configure connections for a Web application
  • Programmatically creating and assigning connections to a ConnectionManager instance

Web ADF resource manager dialog boxes

The Web ADF uses the Connection library to create and manage connections for ArcGIS for Server Local and ArcIMS data sources. The resource manager controls (MapResourceManager, GeocodeResourceManager, and GeoprocessingResourceManager) and provides a Data Source Definition Editor dialog box to define the primary server connection for a resource. For ArcGIS for Server Local and ArcGIS dialog boxes, the option to configure the ConnectionManager capabilities is available in an Advanced Settings dialog box.
See the following screen shots that show the ArcIMS Data Source Definition Editor dialog box and the ArcIMS Resource Advanced Settings dialog box:
See the following screen shots that show the ArcGIS Data Source Definition Editor dialog box and the ArcGIS Resource Advanced Settings dialog box:
When finished configuring connections, a ConnectionManager.xml file is created in the Web application root folder. There is only one ConnectionManager.xml per Web application. The file is used to store the properties defined on the Advanced Settings dialog box. If the file is available at design time, the Web ADF reads the content of the .xml file to populate the Advanced Settings dialog boxes. The primary connection property is the unique key for connections defined in an application. At run time, the data source uses the .xml file to establish the available servers for resource requests. See the following ConnectionManager.xml code example:
[XML] 
<?xml version="1.0"?>
<ESRI.ArcGIS.ADF.Connection>
  <ConnectionManager>
    <Connection
      primary="server1@5300"
      serverType="ArcIMS"
      mode="RoundRobin"
      maxAttempts="20"
      failedCheckInterval="5">
      <Alternate>
        server2@5300
      </Alternate>
      <Alternate>server3@5300</Alternate>
    </Connection>
    <Connection
      primary="server1"
      serverType="ArcGIS"
      mode="Failover"
      maxAttempts="20"
      failedCheckInterval="5">
      <Alternate>
        server2
      </Alternate>
      <Alternate>server3</Alternate>
    </Connection>
  </ConnectionManager>
</ESRI.ArcGIS.ADF.Connection>
In the preceding code example, an ArcIMS TCP and ArcGIS for Server Local connection have been configured to be managed for Web ADF components in the respective Web application. For all ArcIMS TCP connections that use server1@5300 as their primary server, server2@5300 and server3@5300 will also be accessed using the round-robin mode. Any resource manager that defines server1@5300 as the primary connection will use this configuration. 
For all ArcGIS for Server Local connections, the primary connection to server1 will be used until a failure occurs. If a failure occurs, the next alternate server, server2, will be used. The failedCheckInterval parameter defines the number of requests and after the failure, the connection manager waits to check the primary connection to see if it is available. The maxAttempts parameter defines the maximum number of attempts to check if the primary connection becomes available.

Programmatic use

Managing connections with the ConnectionManager involves working with a set of classes in the ESRI.ArcGIS.ADF.Connection library. Connections are added and maintained in a ConnectionManager. A connection is subsequently retrieved from the same ConnectionManager depending on the connection mode (round-robin, failover, or default). Each connection has the option of maintaining a list of alternate connection items that define an alternate server from which to create a connection. Alternates are only used when the connection mode is round-robin or failover. Consider the following classes and properties when configuring a connection manager.

ConnectionManager connections and properties

A ConnectionManager's connections and properties can be configured via a .xml file (see the ConnectionManager.xml code example) or added programmatically. The constructor provides an option for specifying the path to a .xml file and a default identity to use for managed connections (if an identity has not been specified). Once a ConnectionManager is configured, connections are retrieved via the ServerConnection() method. The ServerConnection() method requires two parameters, the connection name and type. It contains logic  for managing connections via the defined connection mode. The ServerConnection() method returns an active ArcGIS for Server (ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection) or ArcIMS (ESRI.ArcGIS.ADF.Connection.IMS.IMSServerConnection) connection. 

ConnectionManager methods

The following table shows important ConnectionManager methods:   
Method name
Returns
Description
Add(Connection)
void
Adds a new Connection instance. Adds ConnectionItems to the Connection instance before adding it to the ConnectionManager.
Find(name, type)
Connection
Finds a connection instance using the name and server type.
ReadXml(XmlDocument)
void
Loads a .xml document with ConnectionManager configuration information.
Remove(Connection)
void
Removes a Connection instance from the ConnectionManager.
ServerConnection(name, type)
IServerConnection
Uses a Connection instance to create an active connection to ArcGIS for Server or ArcIMS. Specifies the name of the primary connection and server type. If the name does not reference an existing connection, a connection is created. The new connection uses the default connection mode and the ConnectionManager identity (if set).

Connection class

The Connection class is used to define the primary connection to a server. Each connection is associated with a unique name used to define the primary server with which it connects. See the property name in the following table for more information. A Connection instance can also store the identity used when connecting, the connection mode, and parameters for retrying failed connections. The following table shows the Connection properties:
Property name
Type
Description
ActiveConnectionItemIndex
int
For round-robin connection modes, provides the current active index of the Connection item (0–number of items). The primary connection returns –1. Other connection modes also return –1.
ConnectionMode
ConnectionMode
Round-robin, failover, and default are the types:
  • Round-robin—Each server (name) defined for the primary connection and any alternate ConnectionItems, is used to create a connection in sequence.
  • Failover—Only one server (name) is used at a time. If a connection fails, the next connection (primary connection or ConnectionItem) is used to define a server from which to create a connection. The first attempt always uses the primary connection.
  • Default—Only the primary connection is used to create a connection.
FailedCheckInterval
int
After a connection fails, this value defines how many requests can be made to the application before checking the status of the failed connection. Valid for round-robin and failover modes only. The default value is 5.
 
For example, assume you set the FailedCheckInterval to 3. If two servers are associated with one connection and the primary  server is unavailable, the secondary server is used exclusively until the third request to the connection. During the third request, the connection attempts to reconnect failed connections, in this case, to the primary server. If unsuccessful, the connection waits another three requests to try again until reaching the maximum number of attempts (MaxAttempts). If set to 0, the connection attempts to reconnect to any server that has failed during each request.
 
The default maximum number of attempts by a connection to connect to any server in its list of server names is 20. This requires at least 20 different server names associated with a single Connection instance to become a factor. This value can only be changed via a Connection constructor (no public property is available). In most cases, this value will not need to be changed.
Identity
Identity
The identity used by the Connection and subsequent ConnectionItems. Valid for ArcGIS for Server and ArcIMS HTTP connections.
Items
ConnectionItemCollection
Use to add or remove ConnectionItem instances to a connection.
Name
string
The name of the connection is determined by the server type. For ArcGIS for Server Local connections, it is the machine name on which an ArcGIS for Server SOM is available. For ArcIMS TCP connections, it is the machine name and port on which an ArcIMS Application Server is available. For ArcIMS HTTP connections, it is the uniform resource locator (URL) to the ArcIMS Servlet connector. Use the name to uniquely identify a Connection instance when using the ConnectionManager to create a connection.
ServerType
string
The following are the valid values:
  • ArcGIS for ArcGIS for Server connections
  • ArcIMS for ArcIMS connections

ConnectionItem properties

A connection can also maintain a list of ConnectionItems, each referencing an alternative connection name. When the connection mode is round-robin or failover, each ConnectionItem associated with a connection can be used. The available services on a server referenced by a ConnectionItem need to match the primary connection.
The following table shows the ConnectionItem properties:
Property name
Type
Description
Name
string
The same as the Connection.Name property except the ConnectionItem defines an alternative server for a connection.

Using the ConnectionManager

The following steps provide a quick overview of how to utilize the ConnectionManager in a custom application. Any application type can take advantage of connection manager capabilities, including Web, desktop, and console applications. Do the following if you have already created a Visual Studio project:
  1. Add references to the connection libraries, ESRI.ArcGIS.ADF.Core.dll and ESRI.ArcGIS.ADF.Connection.Core.dll.
  2. Create a ConnectionManager instance and persist it for the duration of a user's session. If this is a Web application, store it in session. If this is a desktop or stand-alone application, create it as a member variable or expose it via a static class. In essence, only create and populate the ConnectionManager once, then access it as needed.

    See the following code example:
[C#] 
ESRI.ArcGIS.ADF.Connection.ConnectionManager m_ConnectionManager = new
    ESRI.ArcGIS.ADF.Connection.ConnectionManager(null);
  1. Configure connection properties and add them to the connection manager. Create a new Connection class by defining a server name and type. The Connection class defines the default (primary) server to use. Define the connection mode to determine if alternative connection items are needed. Round-robin and failover modes should include Connection Items as alternative servers for a Connection. Add each ConnectionItem to a Connection class, then add the Connection class to the ConnectionManager. A ConnectionManager can manage multiple Connection instances of different server types; therefore, you can manage multiple ArcGIS for Server and ArcIMS connections via the same ConnectionManager. Alternatively, create a .xml file with connection properties, then load it into the ConnectionManager. At this point, the ConnectionManager is ready to be used. See the following code example:
[C#] 
// Define identity to use when connecting to server.
ESRI.ArcGIS.ADF.Identity agsIdentity = new ESRI.ArcGIS.ADF.Identity("user", 
    "password", "domain");

// Create and define primary the Connection.
ESRI.ArcGIS.ADF.Connection.Connection primaryConnectionArcGIS = new
    ESRI.ArcGIS.ADF.Connection.Connection("primaryserver",
    ESRI.ArcGIS.ADF.Connection.ConnectionMode.RoundRobin, agsIdentity, 3, 3);
primaryConnectionArcGIS.ServerType = "ArcGIS";

// Add alternative servers to primary the Connection.
primaryConnectionArcGIS.Items.Add(new ESRI.ArcGIS.ADF.Connection.ConnectionItem(
    "mirrorserver1"));
primaryConnectionArcGIS.Items.Add(new ESRI.ArcGIS.ADF.Connection.ConnectionItem(
    "mirrorserver2"));

// Add Connection to the ConnectionManager.
m_ConnectionManager.Add(primaryConnectionArcGIS);
  1. Use the ConnectionManager to retrieve a valid connection. The ConnectionManager attempts to return an active connection. Regardless of which mode is defined (for example, round-robin, failover, or default), the server name of the default (primary) Connection is used to identify which connection to return. The ConnectionManager.ServerConnection() method returns an active ArcGIS for Server Local or ArcIMS connection (both implement IServerConnection) that can be used to communicate with a service. Note that the connection must be disposed when finished (IServerConnection.Dispose()). See the following code example:
[C#] 
ESRI.ArcGIS.ADF.Connection.IServerConnection serverConnection = m_ConnectionManager.
    ServerConnection("primaryserver", "ArcGIS");

// A connection should be returned alive (connected).
bool isAlive = serverConnection.IsAlive();

// Cast to the appropriate connection type:
// ArcGIS - ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection
// ArcIMS - ESRI.ArcGIS.ADF.Connection.IMS.IMSServerConnection
ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection agsConnection = 
    (ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection)serverConnection;


See Also:

Connecting to an ArcIMS server