IDbConnection Interface
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Represents an open connection to a data source, and is implemented by .NET data providers that access relational databases.
public interface class IDbConnection : IDisposablepublic interface IDbConnection : IDisposabletype IDbConnection = interface
interface IDisposablePublic Interface IDbConnection
Implements IDisposable- Derived
- Implements
Examples
The following example creates instances of the derived classes, SqlCommand and SqlConnection. The SqlConnection is opened and set as the Connection for the SqlCommand. The example then calls ExecuteNonQuery, and closes the connection. To accomplish this, the ExecuteNonQuery is passed a connection string and a query string that is a Transact-SQL INSERT statement.
using System;
using System.Data;
namespace IDbConnectionSample {
class Program {
static void Main(string[] args) {
IDbConnection connection;
// First use a SqlClient connection
connection = new System.Data.SqlClient.SqlConnection(@"Server=(localdb)\V11.0");
Console.WriteLine("SqlClient\r\n{0}", GetServerVersion(connection));
connection = new System.Data.SqlClient.SqlConnection(@"Server=(local);Integrated Security=true");
Console.WriteLine("SqlClient\r\n{0}", GetServerVersion(connection));
// Call the same method using ODBC
// NOTE: LocalDB requires the SQL Server 2012 Native Client ODBC driver
connection = new System.Data.Odbc.OdbcConnection(@"Driver={SQL Server Native Client 11.0};Server=(localdb)\v11.0");
Console.WriteLine("ODBC\r\n{0}", GetServerVersion(connection));
connection = new System.Data.Odbc.OdbcConnection(@"Driver={SQL Server Native Client 11.0};Server=(local);Trusted_Connection=yes");
Console.WriteLine("ODBC\r\n{0}", GetServerVersion(connection));
// Call the same method using OLE DB
connection = new System.Data.OleDb.OleDbConnection(@"Provider=SQLNCLI11;Server=(localdb)\v11.0;Trusted_Connection=yes;");
Console.WriteLine("OLE DB\r\n{0}", GetServerVersion(connection));
connection = new System.Data.OleDb.OleDbConnection(@"Provider=SQLNCLI11;Server=(local);Trusted_Connection=yes;");
Console.WriteLine("OLE DB\r\n{0}", GetServerVersion(connection));
}
public static string GetServerVersion(IDbConnection connection) {
// Ensure that the connection is opened (otherwise executing the command will fail)
ConnectionState originalState = connection.State;
if (originalState != ConnectionState.Open)
connection.Open();
try {
// Create a command to get the server version
// NOTE: The query's syntax is SQL Server specific
IDbCommand command = connection.CreateCommand();
command.CommandText = "SELECT @@version";
return (string)command.ExecuteScalar();
}
finally {
// Close the connection if that's how we got it
if (originalState == ConnectionState.Closed)
connection.Close();
}
}
}
}
Imports System.Data
Class Program
Public Shared Sub Main(args As String())
Dim connection As IDbConnection
' First use a SqlClient connection
connection = New System.Data.SqlClient.SqlConnection("Server=(localdb)\V11.0")
Console.WriteLine("SqlClient" & vbCr & vbLf & "{0}", GetServerVersion(connection))
connection = New System.Data.SqlClient.SqlConnection("Server=(local);Integrated Security=true")
Console.WriteLine("SqlClient" & vbCr & vbLf & "{0}", GetServerVersion(connection))
' Call the same method using ODBC
' NOTE: LocalDB requires the SQL Server 2012 Native Client ODBC driver
connection = New System.Data.Odbc.OdbcConnection("Driver={SQL Server Native Client 11.0};Server=(localdb)\v11.0")
Console.WriteLine("ODBC" & vbCr & vbLf & "{0}", GetServerVersion(connection))
connection = New System.Data.Odbc.OdbcConnection("Driver={SQL Server Native Client 11.0};Server=(local);Trusted_Connection=yes")
Console.WriteLine("ODBC" & vbCr & vbLf & "{0}", GetServerVersion(connection))
' Call the same method using OLE DB
connection = New System.Data.OleDb.OleDbConnection("Provider=SQLNCLI11;Server=(localdb)\v11.0;Trusted_Connection=yes;")
Console.WriteLine("OLE DB" & vbCr & vbLf & "{0}", GetServerVersion(connection))
connection = New System.Data.OleDb.OleDbConnection("Provider=SQLNCLI11;Server=(local);Trusted_Connection=yes;")
Console.WriteLine("OLE DB" & vbCr & vbLf & "{0}", GetServerVersion(connection))
End Sub
Public Shared Function GetServerVersion(connection As IDbConnection) As String
' Ensure that the connection is opened (otherwise executing the command will fail)
Dim originalState As ConnectionState = connection.State
If originalState <> ConnectionState.Open Then
connection.Open()
End If
Try
' Create a command to get the server version
' NOTE: The query's syntax is SQL Server specific
Dim command As IDbCommand = connection.CreateCommand()
command.CommandText = "SELECT @@version"
Return DirectCast(command.ExecuteScalar(), String)
Finally
' Close the connection if that's how we got it
If originalState = ConnectionState.Closed Then
connection.Close()
End If
End Try
End Function
End Class
Remarks
The IDbConnection interface enables an inheriting class to implement a Connection class, which represents a unique session with a data source (for example, a network connection to a server). For more information about Connection classes, see Connecting to a Data Source.
An application does not create an instance of the IDbConnection interface directly, but creates an instance of a class that inherits IDbConnection.
Classes that inherit IDbConnection must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the IDbConnection interface defines the ConnectionTimeout property. In turn, the SqlConnection class inherits this property, and also defines the PacketSize property.
Notes to Implementers
To promote consistency among .NET Framework data providers, name the inheriting class in the form PrvClassname where Prv is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, Sql is the prefix of the SqlConnection class in the System.Data.SqlClient namespace.
When you inherit from the IDbConnection interface, you should implement the following constructors:
| Item | Description |
|---|---|
| PrvConnection() | Initializes a new instance of the PrvConnection class. |
| PrvConnection(string connectionString) | Initializes a new instance of the PrvConnection class when given a string containing the connection string. |
Properties
| ConnectionString |
Gets or sets the string used to open a database. |
| ConnectionTimeout |
Gets the time to wait (in seconds) while trying to establish a connection before terminating the attempt and generating an error. |
| Database |
Gets the name of the current database or the database to be used after a connection is opened. |
| State |
Gets the current state of the connection. |
Methods
| BeginTransaction() |
Begins a database transaction. |
| BeginTransaction(IsolationLevel) |
Begins a database transaction with the specified IsolationLevel value. |
| ChangeDatabase(String) |
Changes the current database for an open |
| Close() |
Closes the connection to the database. |
| CreateCommand() |
Creates and returns a Command object associated with the connection. |
| Dispose() |
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable) |
| Open() |
Opens a database connection with the settings specified by the |
