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 並設定為 Connection 的 SqlCommand。 然後，此範例會呼叫 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會與 和 搭配SqlDataAdapterSqlCommand使用，以在連線到 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.
    }

注意

若要部署高效能應用程式，您必須使用連線共用。 當您使用 .NET Framework Data Provider for SQL Server 時，您不需要啟用連線共用，因為提供者會自動管理此設定，不過您可以修改某些設定。 如需詳細資訊，請參閱 SQL Server 連線共用 (ADO.NET) \(機器翻譯\)。

SqlException如果是由執行SqlCommand的 方法所產生，當嚴重性層級為19或更少時，SqlConnection仍會保持開啟狀態。 當嚴重性層級為 20 或以上時，伺服器通常會關閉 SqlConnection。 但是，使用者可以再次開啟連線，然後繼續進行。

建立 物件實例 SqlConnection 的應用程式，可以藉由設定宣告式或命令式安全性需求，要求所有直接和間接呼叫者擁有足夠的程式碼許可權。 SqlConnection 使用物件提出安全性需求 SqlClientPermission 。 用戶可以使用 對象來確認其程式代碼具有足夠的許可權 SqlClientPermissionAttribute 。 用戶和系統管理員也可以使用 Caspol.exe (代碼啟用安全策略工具) 修改計算機、使用者和企業層級的安全策略。 如需詳細資訊，請參閱 .NET 的安全性。 如需示範如何使用安全性需求的範例，請參閱 代碼啟用安全性和 ADO.NET。

如需從伺服器處理警告和參考訊息的詳細資訊，請參閱 連線事件。 如需 SQL Server 引擎錯誤和錯誤訊息的詳細資訊，請參閱 Database Engine 事件和錯誤。

警告

您可以強制 TCP 而非共享記憶體。 您可以藉由在連接字串中的伺服器名稱前面加上 tcp：，或使用 localhost 來執行此動作。

建構函式

SqlConnection()	初始化 SqlConnection 類別的新執行個體。
SqlConnection(String)	指定包含連接字串的字串時，初始化 SqlConnection 類別的新執行個體。
SqlConnection(String, SqlCredential)	指定不使用 Integrated Security = true 和包含使用者 ID 和密碼之 SqlCredential 物件的連接字串，初始化 SqlConnection 類別的新執行個體。

屬性

AccessToken	取得或設定此連接的存取權杖。
CanCreateBatch	取得值，指出這個 DbConnection 執行個體是否支援 DbBatch 類別。 (繼承來源 DbConnection)
CanRaiseEvents	取得值，指出元件是否能引發事件。 (繼承來源 Component)
ClientConnectionId	最近連線的連線 ID，無論連線是否成功。
ColumnEncryptionKeyCacheTtl	針對 Always Encrypted 功能，取得或設定資料行加密金鑰快取中資料行加密金鑰項目的存留時間。 預設值是 2 小時。 0 表示完全沒有快取。
ColumnEncryptionQueryMetadataCacheEnabled	取得或設定值，指出是否要針對根據已啟用 Always Encrypted 的資料庫執行的參數化查詢，啟用 (true) 或停用 (false) 查詢中繼資料快取。 預設值為 true。
ColumnEncryptionTrustedMasterKeyPaths	可讓您為資料庫伺服器設定受信任的金鑰路徑清單。 如果在處理應用程式查詢時，驅動程式收到的機碼路徑不在清單上，查詢就會失敗。 此屬性會針對受到安全性攻擊危害的 SQL Server 提供額外的保護，此類 SQL Server 會提供假的金鑰路徑，而可能會導致遺漏金鑰存放區認證。
ConnectionString	取得或設定用來開啟 SQL Server 資料庫的字串。
ConnectionTimeout	取得在終止嘗試並產生錯誤前嘗試建立連接的等待時間 (以秒為單位)。
Container	取得包含 IContainer 的 Component。 (繼承來源 Component)
Credential	取得或設定這個連接的 SqlCredential 物件。
Database	取得目前資料庫或要在連接開啟之後使用的資料庫名稱。
DataSource	取得要連線的 SQL Server 執行個體名稱。
DbProviderFactory	取得此 DbProviderFactory 的 DbConnection。 (繼承來源 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)	使用指定的隔離等級開始資料庫異動。
BeginTransaction(IsolationLevel, String)	使用指定的隔離等級和交易名稱開始資料庫交易。
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)	建立包含所有相關資訊的物件，這些資訊是產生用來與遠端物件通訊的所需 Proxy。 (繼承來源 MarshalByRefObject)
Dispose()	執行與釋放 (Free)、釋放 (Release) 或重設 Unmanaged 資源相關聯之應用程式定義的工作。 (繼承來源 DbConnection)
Dispose(Boolean)	釋放 DbConnection 所使用的 Unmanaged 資源，並選擇性地釋放 Managed 資源。 (繼承來源 DbConnection)
DisposeAsync()	以非同步方式處置連線物件。 (繼承來源 DbConnection)
EnlistDistributedTransaction(ITransaction)	將指定的異動登記為分散式異動。
EnlistTransaction(Transaction)	將指定的異動登記為分散式異動。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetLifetimeService()	擷取控制這個執行個體存留期 (Lifetime) 原則的目前存留期服務物件。 (繼承來源 MarshalByRefObject)
GetSchema()	傳回這個 SqlConnection 之資料來源的結構描述資訊。 如需結構描述的詳細資訊，請參閱 SQL Server 結構描述集合。
GetSchema(String)	使用結構描述名稱的特定字串，傳回這個 SqlConnection 之資料來源的結構描述資訊。
GetSchema(String, 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 所指定的設定開啟資料庫連接。 這個方法會叫用虛擬方法 OpenAsync(CancellationToken) 與 CancellationToken.None。 (繼承來源 DbConnection)
OpenAsync(CancellationToken)	非同步版本的 Open()，這個版本會透過 ConnectionString 所指定的屬性設定開啟資料庫連接。 取消語彙基元可用於要求在連線逾時之前捨棄作業。 例外狀況將經由傳回的工作傳播。 如果超過連接逾時期限而未順利連線，傳回的工作會標示為失敗並發生例外狀況。 實作會傳回一項工作，而不需針對集區和非集區的連接封鎖呼叫的執行緒。
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	註冊資料行加密金鑰存放區提供者。
ResetStatistics()	如果啟用統計資料蒐集，則所有值都會重設為零。
RetrieveStatistics()	呼叫方法時，傳回統計資料的名稱值配對集合。
ToString()	傳回任何包含 Component 名稱的 String。 不應覆寫此方法。 (繼承來源 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 and ADO.NET (SQL Server 和 ADO.NET)
• ADO.NET 概觀 \(部分機器翻譯\)