SqlConnection 类

定义

命名空间:

System.Data.SqlClient

程序集:

System.Data.dll

表示与 SQL Server 数据库的连接。 无法继承此类。

public ref class SqlConnection sealed : System::Data::Common::DbConnection, ICloneable

public sealed class SqlConnection : System.Data.Common.DbConnection, ICloneable

type SqlConnection = class
    inherit DbConnection
    interface ICloneable

Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable

继承

Object

MarshalByRefObject

Component

DbConnection

SqlConnection

实现

ICloneable

示例

以下示例创建一个 SqlCommand 和一个 SqlConnection。 打开 SqlConnection 并将其设置为 SqlCommand的 Connection。 然后，该示例调用 ExecuteNonQuery。 为此，ExecuteNonQuery 将传递 SqlConnection 和查询字符串，该字符串是 Transact-SQL INSERT 语句。 当代码退出 using 块时，将自动关闭连接。

private static void CreateCommand(string queryString,
    string connectionString)
{
    using (SqlConnection connection = new SqlConnection(
               connectionString))
    {
        SqlCommand command = new SqlCommand(queryString, connection);
        command.Connection.Open();
        command.ExecuteNonQuery();
    }
}

Public Sub CreateCommand(ByVal queryString As String, _
  ByVal connectionString As String)
    Using connection As New SqlConnection(connectionString)
        Dim command As New SqlCommand(queryString, connection)
        command.Connection.Open()
        command.ExecuteNonQuery()
    End Using
End Sub

注解

SqlConnection 对象表示与 SQL Server 数据源的唯一会话。 使用客户端/服务器数据库系统时，它等效于与服务器的网络连接。 SqlConnection 与 SqlDataAdapter 和 SqlCommand 一起使用，以提高连接到 Microsoft SQL Server 数据库时的性能。 对于所有第三方 SQL Server 产品和其他 OLE DB 支持的数据源，请使用 OleDbConnection。

创建 SqlConnection实例时，所有属性都设置为其初始值。 有关这些值的列表，请参阅 SqlConnection 构造函数。

有关连接字符串中关键字的列表，请参阅 ConnectionString。

如果 SqlConnection 超出范围，则不会关闭它。 因此，必须通过调用 Close 或 Dispose显式关闭连接。 Close 和 Dispose 在功能上是等效的。 如果连接池值 Pooling 设置为 true 或 yes，基础连接将返回给连接池。 另一方面，如果 Pooling 设置为 false 或 no，则与服务器的基础连接实际上已关闭。

注意

从连接池提取或返回到连接池时，不会在服务器上引发登录和注销事件，因为连接在返回到连接池时实际上不会关闭。 有关详细信息，请参阅 SQL Server 连接池（ADO.NET）。

若要确保连接始终关闭，请在 using 块内打开连接，如以下代码片段所示。 这样做可确保在代码退出块时自动关闭连接。

Using connection As New SqlConnection(connectionString)
    connection.Open()
    ' Do work here; connection closed on following line.
End Using

using (SqlConnection connection = new SqlConnection(connectionString))
    {
        connection.Open();
        // Do work here; connection closed on following line.
    }

注意

若要部署高性能应用程序，必须使用连接池。 使用适用于 SQL Server 的 .NET Framework 数据提供程序时，无需启用连接池，因为提供程序会自动管理此配置，尽管可以修改某些设置。 有关详细信息，请参阅 SQL Server 连接池（ADO.NET）。

如果执行 SqlCommand的方法生成 SqlException，则当严重级别为 19 或更少时，SqlConnection 将保持打开状态。 当严重级别为 20 或更大时，服务器通常会关闭 SqlConnection。 但是，用户可以重新打开连接并继续。

创建 SqlConnection 对象的实例的应用程序可以通过设置声明性或命令性安全要求来要求所有直接和间接调用方具有对代码的足够权限。 SqlConnection 使用 SqlClientPermission 对象发出安全要求。 用户可以使用 SqlClientPermissionAttribute 对象来验证其代码是否具有足够的权限。 用户和管理员还可以使用 Caspol.exe（代码访问安全策略工具） 修改计算机、用户和企业级别的安全策略。 有关详细信息，请参阅 .NET中的 安全性。 有关演示如何使用安全要求的示例，请参阅 代码访问安全和 ADO.NET。

有关处理来自服务器的警告和信息性消息的详细信息，请参阅 连接事件。 有关 SQL Server 引擎错误和错误消息的详细信息，请参阅 数据库引擎事件和错误。

谨慎

可以强制 TCP 而不是共享内存。 为此，可以添加 tcp 前缀：到连接字符串中的服务器名称，也可以使用 localhost。

构造函数

SqlConnection()	初始化 SqlConnection 类的新实例。
SqlConnection(String, SqlCredential)	在给定连接字符串的情况下初始化 SqlConnection 类的新实例，该字符串不使用 Integrated Security = true 和包含用户 ID 和密码的 SqlCredential 对象。
SqlConnection(String)	当给定包含连接字符串的字符串时，初始化 SqlConnection 类的新实例。

属性

AccessToken	获取或设置连接的访问令牌。
CanCreateBatch	获取一个值，该值指示此 DbConnection 实例是否支持 DbBatch 类。 (继承自 DbConnection)
CanRaiseEvents	获取一个值，该值指示组件是否可以引发事件。 (继承自 Component)
ClientConnectionId	最新连接尝试的连接 ID，无论尝试是成功还是失败。
ColumnEncryptionKeyCacheTtl	获取或设置 Always Encrypted 功能的列加密密钥缓存中列加密密钥项的生存时间。 默认值为 2 小时。 0 表示根本不进行缓存。
ColumnEncryptionQueryMetadataCacheEnabled	获取或设置一个值，该值指示针对启用了 Always Encrypted 数据库运行的参数化查询是否启用查询元数据缓存（true）或 false。 默认值为 true。
ColumnEncryptionTrustedMasterKeyPaths	允许为数据库服务器设置受信任的密钥路径列表。 如果在处理应用程序查询时驱动程序收到不在列表中的密钥路径，查询将失败。 此属性提供对安全攻击的额外保护，这些攻击涉及泄露的 SQL Server 提供假密钥路径，这可能会导致密钥存储凭据泄露。
ConnectionString	获取或设置用于打开 SQL Server 数据库的字符串。
ConnectionTimeout	获取在终止尝试并生成错误之前尝试建立连接的时间（以秒为单位）。
Container	获取包含 Component的 IContainer。 (继承自 Component)
Credential	获取或设置此连接的 SqlCredential 对象。
Database	获取打开连接后要使用的当前数据库或数据库的名称。
DataSource	获取要连接到的 SQL Server 实例的名称。
DbProviderFactory	获取此 DbConnection的 DbProviderFactory。 (继承自 DbConnection)
DesignMode	获取一个值，该值指示 Component 当前是否处于设计模式。 (继承自 Component)
Events	获取附加到此 Component的事件处理程序的列表。 (继承自 Component)
FireInfoMessageEventOnUserErrors	获取或设置 FireInfoMessageEventOnUserErrors 属性。
PacketSize	获取用于与 SQL Server 实例通信的网络数据包的大小（以字节为单位）。
ServerVersion	获取一个字符串，该字符串包含客户端连接到的 SQL Server 实例的版本。
Site	获取或设置 Component的 ISite。 (继承自 Component)
State	指示在对连接执行的最新网络操作期间 SqlConnection 的状态。
StatisticsEnabled	设置为 true时，启用当前连接的统计信息收集。
WorkstationId	获取标识数据库客户端的字符串。

方法

BeginDbTransaction(IsolationLevel)	在派生类中重写时，启动数据库事务。 (继承自 DbConnection)
BeginDbTransactionAsync(IsolationLevel, CancellationToken)	异步启动数据库事务。 (继承自 DbConnection)
BeginTransaction()	启动数据库事务。
BeginTransaction(IsolationLevel, String)	使用指定的隔离级别和事务名称启动数据库事务。
BeginTransaction(IsolationLevel)	使用指定的隔离级别启动数据库事务。
BeginTransaction(String)	使用指定的事务名称启动数据库事务。
BeginTransactionAsync(CancellationToken)	异步开始数据库事务。 (继承自 DbConnection)
BeginTransactionAsync(IsolationLevel, CancellationToken)	异步开始数据库事务。 (继承自 DbConnection)
ChangeDatabase(String)	更改打开 SqlConnection的当前数据库。
ChangeDatabaseAsync(String, CancellationToken)	异步更改打开连接的当前数据库。 (继承自 DbConnection)
ChangePassword(String, SqlCredential, SecureString)	更改 SqlCredential 对象中指示的用户的 SQL Server 密码。
ChangePassword(String, String)	将连接字符串中指示的用户的 SQL Server 密码更改为提供的新密码。
ClearAllPools()	清空连接池。
ClearPool(SqlConnection)	清空与指定连接关联的连接池。
Close()	关闭与数据库的连接。 这是关闭任何打开连接的首选方法。
CloseAsync()	异步关闭与数据库的连接。 (继承自 DbConnection)
CreateBatch()	返回实现 DbBatch 类的提供程序类的新实例。 (继承自 DbConnection)
CreateCommand()	创建并返回与 SqlConnection关联的 SqlCommand 对象。
CreateDbBatch()	在派生类中重写时，返回实现 DbBatch 类的提供程序类的新实例。 (继承自 DbConnection)
CreateDbCommand()	在派生类中重写时，创建并返回与当前连接关联的 DbCommand 对象。 (继承自 DbConnection)
CreateObjRef(Type)	创建一个对象，其中包含生成用于与远程对象通信的代理所需的所有相关信息。 (继承自 MarshalByRefObject)
Dispose()	执行与释放、释放或重置非托管资源关联的应用程序定义任务。 (继承自 DbConnection)
Dispose(Boolean)	释放 DbConnection 使用的非托管资源，并选择性地释放托管资源。 (继承自 DbConnection)
DisposeAsync()	异步地将连接对象浸入。 (继承自 DbConnection)
EnlistDistributedTransaction(ITransaction)	将指定事务中的登记为分布式事务。
EnlistTransaction(Transaction)	将指定事务中的登记为分布式事务。
Equals(Object)	确定指定的对象是否等于当前对象。 (继承自 Object)
GetHashCode()	用作默认哈希函数。 (继承自 Object)
GetLifetimeService()	检索控制此实例的生存期策略的当前生存期服务对象。 (继承自 MarshalByRefObject)
GetSchema()	返回此 SqlConnection数据源的架构信息。 有关方案的详细信息，请参阅 SQL Server 架构集合。
GetSchema(String, String[])	返回此 SqlConnection 数据源的架构信息，该数据源使用架构名称的指定字符串和限制值的指定字符串数组。
GetSchema(String)	使用架构名称的指定字符串返回此 SqlConnection 数据源的架构信息。
GetSchemaAsync(CancellationToken)	这是 GetSchema()的异步版本。 提供程序应使用适当的实现替代。 可以选择遵守 cancellationToken。 默认实现调用同步 GetSchema() 调用并返回已完成的任务。 如果已通过已取消 cancellationToken，则默认实现将返回已取消的任务。 GetSchema() 引发的异常将通过返回的任务异常属性进行通信。 (继承自 DbConnection)
GetSchemaAsync(String, CancellationToken)	这是 GetSchema(String)的异步版本。 提供程序应使用适当的实现替代。 可以选择遵守 cancellationToken。 默认实现调用同步 GetSchema(String) 调用并返回已完成的任务。 如果已通过已取消 cancellationToken，则默认实现将返回已取消的任务。 GetSchema(String) 引发的异常将通过返回的任务异常属性进行通信。 (继承自 DbConnection)
GetSchemaAsync(String, String[], CancellationToken)	这是 GetSchema(String, String[])的异步版本。 提供程序应使用适当的实现替代。 可以选择遵守 cancellationToken。 默认实现调用同步 GetSchema(String, String[]) 调用并返回已完成的任务。 如果已通过已取消 cancellationToken，则默认实现将返回已取消的任务。 GetSchema(String, String[]) 引发的异常将通过返回的任务异常属性进行通信。 (继承自 DbConnection)
GetService(Type)	返回一个对象，该对象代表由 Component 或其 Container提供的服务。 (继承自 Component)
GetType()	获取当前实例的 Type。 (继承自 Object)
InitializeLifetimeService()	获取生存期服务对象来控制此实例的生存期策略。 (继承自 MarshalByRefObject)
MemberwiseClone()	创建当前 Object的浅表副本。 (继承自 Object)
MemberwiseClone(Boolean)	创建当前 MarshalByRefObject 对象的浅表副本。 (继承自 MarshalByRefObject)
OnStateChange(StateChangeEventArgs)	引发 StateChange 事件。 (继承自 DbConnection)
Open()	使用 ConnectionString指定的属性设置打开数据库连接。
OpenAsync()	Open()的异步版本，该版本使用 ConnectionString指定的设置打开数据库连接。 此方法使用 CancellationToken.None 调用虚拟方法 OpenAsync(CancellationToken)。 (继承自 DbConnection)
OpenAsync(CancellationToken)	Open()的异步版本，该版本使用 ConnectionString指定的属性设置打开数据库连接。 取消令牌可用于请求在连接超时过前放弃操作。 异常将通过返回的任务传播。 如果连接超时时间未成功连接，则返回的任务将标记为出错并出现异常。 实现返回一个任务，而不会阻止池连接和非共用连接的调用线程。
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	注册列加密密钥存储提供程序。
ResetStatistics()	如果启用了统计信息收集，则所有值将重置为零。
RetrieveStatistics()	返回调用方法的时间点统计信息的名称值对集合。
ToString()	返回一个 String，其中包含 Component的名称（如果有）。 不应重写此方法。 (继承自 Component)

事件

Disposed	当组件通过调用 Dispose() 方法释放时发生。 (继承自 Component)
InfoMessage	当 SQL Server 返回警告或信息性消息时发生。
StateChange	在连接状态发生更改时发生。 (继承自 DbConnection)

显式接口实现

ICloneable.Clone()	创建一个新对象，该对象是当前实例的副本。
IDbConnection.BeginTransaction()	开始数据库事务。 (继承自 DbConnection)
IDbConnection.BeginTransaction(IsolationLevel)	使用指定的隔离级别开始数据库事务。 (继承自 DbConnection)
IDbConnection.CreateCommand()	创建并返回与当前连接关联的 DbCommand 对象。 (继承自 DbConnection)

另请参阅

• 连接到 ADO.NET中的数据源
• SQL Server 和 ADO.NET
• ADO.NET 概述