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:
Add code to Instantiate the 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.
.NET Shared Memory Connections
The standard ADO .NET connection to a remote InterSystems IRIS instance is over TCP/IP. To maximize performance, InterSystems IRIS also offers a shared memory connection for .NET applications running on the same machine as an InterSystems IRIS instance. This connection avoids potentially expensive calls into the kernel network stack, providing optimal low latency and high throughput for .NET operations.
If a connection specifies server address localhost or 127.0.0.1, shared memory will be used by default. TCP/IP will be used if the actual machine address is specified. The connection will automatically fall back to TCP/IP if the shared memory device fails or is not available.
Shared memory can be disabled in the connection string by setting the SharedMemory property to false. For example, the following connection string will not use shared memory, even though the server address is specified as localhost.
"Server=localhost;Port=51774;Namespace=user;Password = SYS;User ID = _system;SharedMemory=false"
Shared memory is not used for TLS connections. The log will include information on whether a shared memory connection was attempted and if it was successful.
Note:
Shared memory connections do not work across container boundaries
InterSystems does not currently support shared memory connections between two different containers. If a client tries to connect across container boundaries using localhost or 127.0.0.1, the connection mode will default to shared memory, causing it to fail. This applies regardless of whether the Docker --network host option is specified. You can guarantee a TCP/IP connection between containers either by specifying the actual hostname for the server address, or by disabling shared memory in the connection string (as demonstrated above).
Shared memory connections can be used without problems when the server and client are in the same container.
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.
