簡介
繼承層次結構
SystemObject
SystemMarshalByRefObject
System.ComponentModelComponent
System.Data.CommonDbConnection
System.Data.SqlClientSqlConnection
程式集
System.Data（在 System.Data.dll 中）
語法
[pre]Public NotInheritable Class SqlConnection _ Inherits DbConnection _ Implements ICloneable[pre]
<li class="list-num-1-1 list-num-paddingleft-1">
public sealed class SqlConnection : DbConnection,
</li><li class="list-num-1-2 list-num-paddingleft-1">
ICloneable
</li>[pre]public ref class SqlConnection sealed : public DbConnection, ICloneable[pre][<Sealed>]type SqlConnection = class inherit DbConnection interface ICloneable end
SqlConnection 類型公開以下成員。
構造函式
| 名稱 | 說明 | |
| SqlConnection | 初始化 SqlConnection 類的新實例。 | |
| SqlConnection(String) | 如果給定包含連線字元串的字元串，則初始化 SqlConnection 類的新實例。 | |
| SqlConnection(String, SqlCredential) | 初始化給定連線字元串的 SqlConnection 類的新實例，而不使用包含用戶識別號和密碼的 Integrated Security = true 和 SqlCredential 對象。 |
頁首
屬性
| 名稱 | 說明 | |
| ClientConnectionId | 最近連線嘗試連線的 ID，無論該嘗試是成功還是失敗。 | |
| ConnectionString | 獲取或設定用於打開 SQL Server 資料庫的字元串。 （重寫 DbConnectionConnectionString。） | |
| ConnectionTimeout | 獲取在嘗試建立連線時終止嘗試並生成錯誤之前所等待的時間。 （重寫 DbConnectionConnectionTimeout。） | |
| Container | 獲取 IContainer，它包含 Component。 （繼承自 Component。） | |
| Credential | 獲取或設定此連線的 SqlCredential 對象。 | |
| Database | 獲取當前資料庫或連線打開後要使用的資料庫的名稱。 （重寫 DbConnectionDatabase。） | |
| DataSource | 獲取要連線的 SQL Server 實例的名稱。 （重寫 DbConnectionDataSource。） | |
| FireInfoMessageEventOnUserErrors | 獲取或設定 FireInfoMessageEventOnUserErrors 屬性。 | |
| PacketSize | 用來與 SQL Server 的實例進行通信的網路數據包的大小，以位元組為單位。 | |
| ServerVersion | 獲取包含客戶端連線的 SQL Server 實例的版本的字元串。 （重寫 DbConnectionServerVersion。） | |
| Site | 獲取或設定 Component 的 ISite。 （繼承自 Component。） | |
| State | 指示最近在連線上執行網路操作時， SqlConnection 的狀態。 （重寫 DbConnectionState。） | |
| StatisticsEnabled | 如果設定為 true，則對當前連線啟用統計信息收集。 | |
| WorkstationId | 獲取標識資料庫客戶端的一個字元串。 |
頁首
方法
| 名稱 | 說明 | |
| BeginTransaction | 開始資料庫事務。 | |
| BeginTransaction(IsolationLevel) | 以指定的隔離級別啟動資料庫事務。 | |
| BeginTransaction(String) | 以指定的事務名稱啟動資料庫事務。 | |
| BeginTransaction(IsolationLevel, String) | 以指定的隔離級別和事務名稱啟動資料庫事務。 | |
| ChangeDatabase | 為打開的 SqlConnection 更改當前資料庫。 （重寫 DbConnectionChangeDatabase(String)。） | |
| ChangePassword(String, String) | 將連線字元串中指示的用戶的 SQL Server 密碼更改為提供的新密碼。 | |
| ChangePassword(String, SqlCredential, SecureString) | 更改 SqlCredential 對象指示的用戶的 SQL Server 密碼。 | |
| ClearAllPools | 清空連線池。 | |
| ClearPool | 清空與指定連線關聯的連線池。 | |
| Close | 關閉與資料庫的連線。 此方法是關閉任何已打開連線的首選方法。 （重寫 DbConnectionClose。） | |
| CreateCommand | 創建並返回一個與 SqlConnection 關聯的 SqlCommand 對象。 | |
| CreateObjRef | 創建一個對象，該對象包含生成用於與遠程對象進行通信的代理所需的全部相關信息。 （繼承自 MarshalByRefObject。） | |
| Dispose | 釋放由 Component 使用的所有資源。 （繼承自 Component。） | |
| EnlistDistributedTransaction | 在指定的事務中登記為分散式事務。 | |
| EnlistTransaction | 在指定的事務中登記為分散式事務。 （重寫 DbConnectionEnlistTransaction(Transaction)。） | |
| Equals(Object) | 確定指定的對象是否等於當前對象。 （繼承自 Object。） | |
| GetHashCode | 用作特定類型的哈希函式。 （繼承自 Object。） | |
| GetLifetimeService | 檢索控制此實例的生存期策略的當前生存期服務對象。 （繼承自 MarshalByRefObject。） | |
| GetSchema | 返回此 SqlConnection 的數據源的架構信息。 有關架構的更多信息，請 SQL Server 架構集合參見。 （重寫 DbConnectionGetSchema。） | |
| GetSchema(String) | 使用指定的架構名稱字元串，返回此 SqlConnection 的數據源的架構信息。 （重寫 DbConnectionGetSchema(String)。） | |
| GetSchema(String, String) | 使用指定的架構名稱字元串和指定的限制值字元串數組，返回此 SqlConnection 的數據源的架構信息。 （重寫 DbConnectionGetSchema(String, String)。） | |
| GetType | 獲取當前實例的 Type。 （繼承自 Object。） | |
| InitializeLifetimeService | 獲取控制此實例的生存期策略的生存期服務對象。 （繼承自 MarshalByRefObject。） | |
| Open | 使用 ConnectionString 所指定的屬性設定打開資料庫連線。 （重寫 DbConnectionOpen。） | |
| OpenAsync | Open的異步版本，打開由 ConnectionString指定的設定的資料庫連線。 此方法通過 CancellationToken.None 調用虛擬方法 OpenAsync。 （繼承自 DbConnection。） | |
| OpenAsync(CancellationToken) | Open的異步版本，打開由 ConnectionString指定的屬性設定的資料庫連線。 取消標記可用於在連線逾時超過前請求放棄操作。 異常將通過返回的任務傳播。 如果在未成功連線的情況下連線逾時時間已過，則返回的任務將被標記為“附帶異常出錯”。 實現返回一個不帶有用於共用和非共用連線的鎖定調用執行緒的“任務”。 （重寫 DbConnectionOpenAsync(CancellationToken)。） | |
| ResetStatistics | 如果啟用統計信息收集，則所有的值都將重置為零。 | |
| RetrieveStatistics | 調用該方法時，將返回統計信息的名稱值對集合。 | |
| ToString | 返回包含 Component 的名稱的 String（如果有）。 不應重寫此方法。 （繼承自 Component。） |
頁首
事件
| 名稱 | 說明 | |
| Disposed | 當通過調用 Dispose 方法釋放組件時發生。 （繼承自 Component。） | |
| InfoMessage | 當 SQL Server 返回一個警告或信息性訊息時發生。 | |
| StateChange | 當事件狀態更改時發生。 （繼承自 DbConnection。） |
頁首
顯式接口實現
| 名稱 | 說明 | |
| ICloneableClone | 創建作為當前實例副本的新對象。 | |
| IDbConnectionBeginTransaction | 開始資料庫事務。 （繼承自 DbConnection。） | |
| IDbConnectionBeginTransaction(IsolationLevel) | 以指定的 IsolationLevel 值開始一個資料庫事務。 （繼承自 DbConnection。） | |
| IDbConnectionCreateCommand | 創建並返回與當前連線關聯的 DbCommand 對象。 （繼承自 DbConnection。） |
頁首
備註
SqlConnection 對象表示單個會話中對 SQL Server 數據源。 在客戶端/伺服器資料庫系統中，它等效於一個到伺服器的網路連線。 當連線到 Microsoft SQL Server 資料庫時，SqlConnection 與 SqlDataAdapter 和 SqlCommand 一起使用來提高性能。 對於所有第三方 SQL Server 產品，同時，其他 OLE DB 支持數據源，請使用 OleDbConnection。
當創建 SqlConnection 的實例時，所有屬性都設定為它們的初始值。 有關這些值的列表，請參見 SqlConnection 構造函式。
有關連線字元串中的關鍵字列表，請參見 ConnectionString。
如果 SqlConnection 超出範圍，則不會將其關閉。 因此，必須通過調用Close或Dispose顯式關閉該連線。Close 和 Dispose 的功能等效。 如果連線池值 Pooling 設定為 true 或 yes，則基礎連線將返回到連線池。 另一方面，如果 Pooling 設定為 false 或 no，則實際上會關閉到伺服器的基礎連線。
| 說明 |
| 在從連線池中獲取連線或將連線返回到連線池時，將不會在伺服器上引發登錄和註銷事件，因為在將連線返回到連線池時，將不會實際關閉連線。 有關更多信息，請參見SQL Server Connection Pooling (ADO.NET)。 |
若要確保連線始終關閉，請在 using 塊內部打開連線，如下面的代碼段所示。 這樣可確保在代碼退出代碼塊時自動關閉連線。
[pre]Using connection As New SqlConnection(connectionString) connection.Open() ' Do work here; connection closed on following line.End Using[pre]
<li class="list-num-1-1 list-num-paddingleft-1">
using (SqlConnection connection = new SqlConnection(connectionString))
</li><li class="list-num-1-2 list-num-paddingleft-1">
{
</li><li class="list-num-1-3 list-num-paddingleft-1">
connection.Open();
</li><li class="list-num-1-4 list-num-paddingleft-1">
// Do work here; connection closed on following line.
</li><li class="list-num-1-5 list-num-paddingleft-1">
}
</li>
| 說明 |
| 若要部署高性能應用程式，則必須使用連線池。 當為 SQL Server時使用 .NET Framework 數據提供程式，您不必啟用合併的連線，因為提供程式自動管理此，不過，可以修改某些設定。 有關更多信息，請參見SQL Server Connection Pooling (ADO.NET)。 |
如果執行 SqlCommand 的方法生成 SqlException，那么當嚴重級別小於等於 19 時，SqlConnection 將仍保持打開狀態。 當嚴重級別大於等於 20 時，伺服器通常會關閉 SqlConnection。 但是，用戶可以重新打開連線並繼續。
創建 SqlConnection 對象的實例的應用程式可通過設定聲明性或命令性安全要求，要求所有直接和間接的調用方都具有訪問代碼的充分許可權。SqlConnection 使用 SqlClientPermission 對象設定安全要求。 用戶可以通過使用 SqlClientPermissionAttribute 對象來驗證他們的代碼是否具有足夠的許可權。 用戶和管理員還可以使用Caspol.exe（代碼訪問安全策略工具） 來修改計算機、用戶和企業級別的安全策略。 有關更多信息，請參見.NET Framework 中的安全性。 有關演示如何使用安全請求的示例，請參見 Code Access Security and ADO.NET。
有關處理來自伺服器的警告和信息性訊息的更多信息，請參見Working with Connection Events。SQL Server 引擎錯誤和錯誤訊息。SQL Server Books online 文檔。
| 警告 |
| 可以強制 TCP 而不是共享記憶體。 可通過在連線字元串中的伺服器名稱之前添加 tcp: 前綴或使用本地主機來達到此目的。 |
| Topic | Location |
| 如何：創建與 SQL Server 資料庫的連線 | Visual Studio 中的數據訪問 |
| 如何：創建與 SQL Server 資料庫的連線 | Visual Studio 中的數據訪問 |
示例
下面的示例創建一個 SqlCommand 和一個 SqlConnection。SqlConnection 打開，並設定為 SqlCommand 的 Connection。 該示例然後調用 ExecuteNonQuery。 為此，ExecuteNonQuery 通過連線字元串和是 Transact-SQL INSERT 語句中的查詢字元串。 當代碼使用塊退出時，連線自動關閉。
[pre]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 UsingEnd Sub[pre]
<li class="list-num-1-1 list-num-paddingleft-1">
private static void CreateCommand(string queryString,
</li><li class="list-num-1-2 list-num-paddingleft-1">
string connectionString)
</li><li class="list-num-1-3 list-num-paddingleft-1">
{
</li><li class="list-num-1-4 list-num-paddingleft-1">
using (SqlConnection connection = new SqlConnection(
</li><li class="list-num-1-5 list-num-paddingleft-1">
connectionString))
</li><li class="list-num-1-6 list-num-paddingleft-1">
{
</li><li class="list-num-1-7 list-num-paddingleft-1">
SqlCommand command = new SqlCommand(queryString, connection);
</li><li class="list-num-1-8 list-num-paddingleft-1">
command.Connection.Open();
</li><li class="list-num-1-9 list-num-paddingleft-1">
command.ExecuteNonQuery();
</li><li class="list-num-1-10 list-num-paddingleft-1">
}
</li><li class="list-num-1-11 list-num-paddingleft-1">
}
</li><li class="list-num-1-12 list-num-paddingleft-1"></li>
版本
.NET Framework
受以下版本支持：4.5、4、3.5、3.0、2.0、1.1、1.0
.NET Framework Client Profile
受以下版本支持：4、3.5 SP1
平台
Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008（不支持伺服器核心角色）, Windows Server 2008 R2（支持帶 SP1 或更高版本的伺服器核心角色；不支持 Itanium）
.NET Framework 並不是對每個平台的所有版本都提供支持。有關支持的版本的列表，請參見.NET Framework 系統要求。
執行緒安全
此類型的任何公共 static（在 Visual Basic 中為 Shared） 成員都是執行緒安全的。但不保證所有實例成員都是執行緒安全的。
請參見
參考
System.Data.SqlClient 命名空間
其他資源
Connecting to a Data Source (ADO.NET)
Using the .NET Framework Data Provider for SQL Server
ADO.NET 託管提供程式和數據集開發人員中心)
