Connecting to the Database with .NET
This section describes how to create a connection between your .NET client application and an InterSystems server using an IRISConnection object.
Establishing Connections with .NET
The code below establishes a connection to a namespace named USER. See “Connection Parameter Options” for a complete list of parameters that can be set when instantiating a connection object.
The following simple method could be called to start a connection:
public IRISConnection Conn;
private void CreateConnection(){
try {
Conn = new IRISConnection();
Conn.ConnectionString =
"Server=localhost; Port=51773; Namespace=USER;"
+ "Password=SYS; User ID=_SYSTEM;";
Conn.Open();
}
catch (Exception eConn){
MessageBox.Show("CreateConnection error: " + eConn.Message);
}
}
Once the object has been created, it can be shared among all the classes that need it. The connection object can be opened and closed as necessary. You can do this explicitly by using Conn.Open() and Conn.Close(). If you are using an ADO.NET Dataset, instances of DataAdapter will open and close the connection automatically, as needed.
Troubleshooting .NET Client Connections
A .NET client that attempts to connect to an InterSystems server needs the following information:
-
A URL that provides the server IP address, port number, and namespace.
-
If the connection uses passwords, you must specify a case-sensitive username and password.
Check the following points if you have any problems:
-
Make sure that the server process is installed and running.
-
Make sure that you know the IP address of the machine on which the server process is running.
-
Make sure that you know the TCP/IP port number on which the server is listening.
-
Make sure that you have a valid username and password to use to establish a connection. (You can manage usernames and passwords using the Management Portal: System Administration > Security > Users).
-
Make sure that your connection URL includes a valid namespace. This should be the namespace containing the classes and data your program uses.
Connection Pooling with .NET
Connection pooling is on by default. The following connection string parameters can be used to control various aspects of connection pooling:
-
Pooling — Defaults to true. Set Pooling to false to create a connection with no connection pooling.
-
Min Pool Size and Max Pool Size — Default values are 0 and 100. Set these parameters to specify the maximum and minimum (initial) size of the connection pool for this specific connection string.
-
Connection Reset and Connection Lifetime — Set Connection Reset to true to turn on the pooled connection reset mechanism. Connection Lifetime specifies the number of seconds to wait before resetting an idle pooled connection. The default value is 0.
For example, the following connect string sets the initial size of the connection pool to 2 and the maximum number of connections to 5, and activates connection reset with a maximum connection idle time of 3 seconds:
Conn.ConnectionString =
"Server = localhost;"
+ " Port = 51774;"
+ " Namespace = USER;"
+ " Password = SYS;"
+ " User ID = _SYSTEM;"
+ " Min Pool Size = 2;"
+ " Max Pool Size = 5;"
+ " Connection Reset = true;"
+ " Connection Lifetime = 3;";
See the “Quick Reference for the .NET Managed Provider” for more details on the various connection pooling methods and properties.
