SqlConnection 類別

定義

命名空間:

Microsoft.Data.SqlClient

組件:

Microsoft.Data.SqlClient.dll

套件:

Microsoft.Data.SqlClient v7.0.1

代表與 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

繼承

DbConnection

SqlConnection

實作

ICloneable

範例

以下範例會產生 a SqlCommand 和 SqlConnection。 打開 並SqlConnection設定為 Connection 。SqlCommand 此範例接著將 稱為 ExecuteNonQuery。 為達成此目標，ExecuteNonQuery 會傳遞一個 SqlConnection 和一個查詢字串，該查詢字串是 Transact-SQL INSERT 陳述式。 當程式碼離開使用區塊時，連線會自動關閉。

using System;
using System.Data;
using Microsoft.Data.SqlClient;

namespace SqlCommand_ExecuteNonQuery
{
    class Program
    {
        static void Main()
        {
            string str = "Data Source=(local);Initial Catalog=Northwind;"
                + "Integrated Security=SSPI";
            string qs = "SELECT OrderID, CustomerID FROM dbo.Orders;";
            CreateCommand(qs, str);
        }
        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();
            }
        }
    }
}

備註

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，則與伺服器的底層連線實際上是關閉的。

Note

從連接集區中擷取連接或將連接傳回連接集區時，系統不會在伺服器上引發登入和登出事件，因為當連接傳回連接集區時，連接實際上並未關閉。 如需詳細資訊，請參閱 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.  
}  

Note

要部署高效能應用程式，必須使用連線池。 當你使用 .NET Framework Data Provider for SQL Server 時，你不需要啟用連線池，因為提供者會自動管理，雖然你可以修改一些設定。 如需詳細資訊，請參閱 SQL Server 連線共用 (ADO.NET)。

若 a SqlException 是由執行 的方法 SqlCommand產生，則當嚴重程度等級低於 19 時，該 SqlConnection 保持開啟狀態。 當嚴重程度等級達到 20 或以上時，伺服器通常會關閉 SqlConnection。 不過，使用者可以重新開啟連線並繼續使用。

建立物件實例 SqlConnection 的應用程式可以透過設定宣告式或命令式安全要求，要求所有直接與間接呼叫者對程式碼擁有足夠的權限。 SqlConnection 使用物件 SqlClientPermission 提出安全要求。 使用者可以透過使用物件 SqlClientPermissionAttribute 來驗證其程式碼是否擁有足夠的權限。 使用者與管理員也可使用 Caspol.exe（程式碼存取安全政策工具） 在機器、使用者及企業層級修改安全政策。 如需詳細資訊，請參閱 .NET 中的安全性。 關於如何使用安全需求，請參見 程式碼存取安全與 ADO.NET。

關於處理伺服器警告與資訊訊息的更多資訊，請參見 連線事件。 欲了解更多關於SQL Server引擎錯誤與錯誤訊息的資訊，請參見 資料庫引擎 事件與錯誤。

注意事項

你可以強制使用 TCP 取代共用記憶體。 你可以在 連接字串 裡把 tcp： 放在伺服器名稱前綴，或者用 localhost。

建構函式

名稱	Description
SqlConnection()	初始化 SqlConnection 類別的新執行個體。
SqlConnection(String, SqlCredential)	初始化一個新實例， SqlConnection 給定一個不使用 Integrated Security = true 包含使用者 ID 和密碼的連接字串和 SqlCredential 物件。
SqlConnection(String)	當給定包含連接字串的字串時，初始化該類別的新 SqlConnection 實例。

屬性

名稱	Description
AccessToken	取得或設定連線的存取權杖。
AccessTokenCallback	取得或設定連線的存取權杖回撥。
CanCreateBatch	會得到一個值，表示這個 SqlConnection 實例是否支援該 DbBatch 類別。
ClientConnectionId	這是最近一次連線嘗試的連線 ID，不論嘗試成功還是失敗。
ColumnEncryptionKeyCacheTtl	取得或設定欄位加密金鑰在「 始終加密 」功能中欄位加密金鑰條目的存活時間。 預設數值是2小時。 0 表示完全沒有快取。
ColumnEncryptionQueryMetadataCacheEnabled	取得或設定一個值，指示對於對啟用 Always Encrypted 的資料庫執行的參數化查詢是否啟用（true）或是否啟用（false）。 預設值為 True。
ColumnEncryptionTrustedMasterKeyPaths	可讓您為資料庫伺服器設定受信任的金鑰路徑清單。 若在處理應用程式查詢時，驅動程式收到不在清單上的金鑰路徑，查詢將失敗。 此特性可額外防護涉及被入侵的 SQL Server 提供假金鑰路徑的安全攻擊，可能導致金鑰庫憑證外洩。
CommandTimeout	在終止執行指令並產生錯誤前，會取得預設的等待時間（以秒為單位）。 預設值為 30 秒。
ConnectionString	取得或設定用來開啟 SQL Server 資料庫的字串。
ConnectionTimeout	在嘗試建立連線時，有時間等待，然後終止嘗試並產生錯誤。
Credential	取得或設定 SqlCredential 此連線的物件。
Database	取得目前資料庫名稱或開啟連線後要使用的資料庫名稱。
DataSource	取得要連接的 SQL Server 實例名稱。
FireInfoMessageEventOnUserErrors	取得或設定該 FireInfoMessageEventOnUserErrors 屬性。
PacketSize	取得用於與 SQL Server 實例通訊的網路封包大小（以位元組為單位）。
RetryLogicProvider	取得或設定一個值，指定綁定到此指令的物件。SqlRetryLogicBaseProvider
ServerProcessId	取得該主動連線的伺服器程序 ID（SPID）。
ServerVersion	會取得一個字串，包含用戶端所連接的 SQL Server 實例版本。
SspiContextProvider	取得或設定 SspiContextProvider SSPI 上下文的實例。 若未設定，將使用該平台的預設值。
State	表示在最近一次網路操作中，連線的狀態 SqlConnection 。
StatisticsEnabled	當 設定為 true時，能收集目前連線的統計資料。
WorkstationId	會取得一個字串來識別資料庫客戶端。

方法

名稱	Description
BeginTransaction()	啟動資料庫交易。
BeginTransaction(IsolationLevel, String)	啟動一個指定的隔離層級和交易名稱的資料庫交易。
BeginTransaction(IsolationLevel)	啟動指定的隔離層級資料庫交易。
BeginTransaction(String)	啟動一個以指定交易名稱的資料庫交易。
ChangeDatabase(String)	將當前資料庫變更為開啟 SqlConnection的 。
ChangePassword(String, SqlCredential, SecureString)	變更 SqlCredential 物件中所指出使用者的 SQL Server 密碼。
ChangePassword(String, String)	將使用者的 SQL Server 密碼（連接字串）變更為所提供的新密碼。
ClearAllPools()	會清空連線池。
ClearPool(SqlConnection)	清空與指定連線相關的連線池。
Close()	關閉了與資料庫的連線。 這是關閉任何開路連接的首選方法。
CreateCommand()	建立並回傳 SqlCommand 與 SqlConnection相關聯的物件。
GetSchema()	回傳此 SqlConnection資料來源的結構資訊。 欲了解更多關於方案的資訊，請參見 SQL Server 結構集合。
GetSchema(String, String[])	回傳此 SqlConnection 資料來源的結構資訊，並使用指定的字串作為結構名稱，並以指定的字串陣列作為限制值。
GetSchema(String)	會使用指定的字串作為結構名稱，回傳該 SqlConnection 資料庫的結構資訊。
Open()	開啟一個資料庫連線，並依照 ConnectionString.
Open(SqlConnectionOverrides)	開啟一個資料庫連線，並依照 ConnectionString.
OpenAsync(CancellationToken)	非同步版本Open()的 ，開啟資料庫連線，並依照 。ConnectionString 取消權杖可用來請求在連線逾時前放棄操作。 例外將透過回傳的任務傳播。 若連線逾時時間過後未成功連接，回傳的任務將被標記為錯誤且有例外。 實作在不阻擋呼叫執行緒的情況下，無論是池中連線還是非池中連線，都能回傳任務。
OpenAsync(SqlConnectionOverrides, CancellationToken)	非同步版本Open()的 ，開啟資料庫連線，並依照 。ConnectionString 取消權杖可用來請求在連線逾時前放棄操作。 例外將透過回傳的任務傳播。 若連線逾時時間過後未成功連接，回傳的任務將被標記為錯誤且有例外。 實作在不阻擋呼叫執行緒的情況下，無論是池中連線還是非池中連線，都能回傳任務。
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	登錄欄位加密金鑰儲存提供者。 這個函式在應用程式中應該只呼叫一次。 這會對字典進行淺層複製，讓應用程式無法在自訂提供者清單設定後更改。 Windows 憑證存放區、CNG Store 和 CSP 可用的內建資料行主要金鑰存放區提供者會預先註冊。
RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	註冊實例上的 SqlConnection 加密金鑰儲存提供者。 若此函式已被呼叫，任何使用靜態 RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) 方法註冊的提供者將被忽略。 這個函式可以呼叫不只一次。 這會對字典進行淺層複製，讓應用程式無法在自訂提供者清單設定後更改。
ResetStatistics()	若啟用統計收集，所有數值會重置為零。
RetrieveInternalInfo()	回傳一個名稱值對的內部屬性集合，該集合在方法被呼叫時點。
RetrieveStatistics()	回傳方法被呼叫時的統計資料對集合。

事件

名稱	Description
InfoMessage	當 SQL Server 回傳警告或資訊訊息時，會發生這種情況。

明確介面實作

名稱	Description
ICloneable.Clone()	建立一個新的物件，該物件是目前實例的複製品。