使用 Microsoft.Data.SqlClient 連線到資料來源

SqlConnection代表與 SQL Server、Azure SQL Database、Azure SQL 受控執行個體 或 Microsoft Fabric 中的 SQL 資料庫的一個邏輯連線。 開啟物件時,若連線集區中有可用的連線,便會從中取得實體連線。 關閉或處理後,該實體連接會回到池中。

使用生命週期短的 SqlConnection 物件來處理工作單位。 不要讓應用程式的單一全域連線持續開啟。

Prerequisites

  • .NET 10 SDK 或後來支援的 .NET SDK。 SDK 可運行於 Windows、Linux 及 macOS 上。 它也會編譯每個範例的 .NET Framework 版本,該版本僅能在 Windows 上運行,且需要 .NET Framework 4.8.1。
  • 一個你可以在 SQL Server、Azure SQL Database、Azure SQL 受控執行個體 或 Microsoft Fabric 中的 SQL 資料庫中連接的資料庫。

建立專案

Microsoft.Data.SqlClient 7.0 及更新版本需要版本相符的 Microsoft.Data.SqlClient.Extensions.Azure 套件,以支援驅動程式提供的 Microsoft Entra ID 驗證模式,例如 Active Directory Default。 如果你的應用程式只使用 SQL 認證或 Windows 整合認證,你可以省略它。

在空資料夾中執行以下指令:

dotnet new console --framework net10.0 --name SqlClientConnect
cd SqlClientConnect
dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1

本文中的範例讀取了 SQL_CONNECTION_STRING 環境變數中的 連接字串。 在你執行範例前先設定好。 關於 連接字串 格式,請參見 Connection strings。

除了交易範例外,每個範例都是完整的程式。 要執行一個,先用它取代 Program.cs 的內容,然後執行 dotnet run。 交易範例程式是供您自訂方法使用的程式片段。 .NET 分頁使用最上層陳述式、隱含using指令及 await using。 .NET Framework 分頁使用 C# 7.3,但沒有 await using,因此改用using語句。

開啟連線

在非同步程式碼中呼叫 OpenAsync,或在同步程式碼中呼叫 Open。 使用 await using 或 using 宣告連線,以便在程式碼離開作用域時將其丟棄,即使拋出例外也一樣。

使用 Windows 整合式驗證時,連線會使用程序的身分。 對於網頁應用程式或 Windows 服務來說,那是應用程式池或服務帳號,不是已登入的使用者。 欲了解更多資訊,請參閱 選擇認證模式。

這個完整程式會開啟連線,報告每次狀態變更,並讀取兩個伺服器屬性:

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString);
connection.StateChange += (_, e) =>
    Console.WriteLine($"State: {e.OriginalState} to {e.CurrentState}");

await connection.OpenAsync();

await using var command = new SqlCommand(
    """
    SELECT CAST(SERVERPROPERTY('Edition') AS nvarchar(128)),
           CAST(SERVERPROPERTY('EngineEdition') AS int);
    """,
    connection);

await using (SqlDataReader reader = await command.ExecuteReaderAsync())
{
    await reader.ReadAsync();
    Console.WriteLine($"Edition: {reader.GetString(0)}");
    Console.WriteLine($"EngineEdition: {reader.GetInt32(1)}");
}

針對 SQL Server 2025 企業版,輸出為:

State: Closed to Open
Edition: Enterprise Edition: Core-based Licensing (64-bit)
EngineEdition: 3
State: Open to Closed

當程式結束時,當連線被丟棄時,最後一行就會出現。

關閉並處置連線

每次結束連線後一定要關閉,讓實體連線回到池子。 await using 和 using 語句會在程式碼離開區塊時釋放該連線,包括在擲回未處理的例外狀況時。 你也可以直接打電話 Close 或 Dispose 聯絡。 Close 和 Dispose 對物理連線有相同效果。

請遵循以下規則:

  • 應先釋放讀取器和命令,再釋放擁有它們的連線。
  • 不要依賴垃圾回收來回傳連線到連線池。 若連線離開作用域卻未關閉,連線不會立即回傳,連線池可能會耗盡可用連線。
  • 在類別終結器中,不要對連線、讀取器或任何其他受管理物件呼叫 Close 或 Dispose。 終結者應該只釋放其類別直接擁有的未管理資源。 更多資訊請參見 垃圾回收。
  • 之後 Close,你可以在同一個物件上再次呼叫 Open 。 在 Dispose 之後,建立一個新物件。

啟用池化時,關閉連線會讓它回到池中,但不會關閉網路連線。 當連線被重用時,池會重置會話狀態。 更多資訊請參閱 SQL Server 連線池。

使用非同步 API

在網路伺服器、服務、使用者介面及工作者中,使用非同步呼叫進行網路綁定的資料庫工作:

  • OpenAsync(cancellationToken)
  • ExecuteNonQueryAsync(cancellationToken)
  • ExecuteReaderAsync(cancellationToken)
  • ExecuteScalarAsync(cancellationToken)
  • ReadAsync(cancellationToken)

在目前非同步操作結束前,不要對連線、指令或讀取器啟動另一個操作。

套用取消與逾時設定

在每一次非同步資料庫呼叫中傳遞呼叫端的 CancellationToken。 取消要求司機停止待完成的工作,但不保證會立即生效。 繼續使用設有限制的連線和命令逾時設定。

這些控制有不同的範圍:

管理 Scope
Connect Timeout 連線建立,或等待來自連線池的連線
SqlCommand.CommandTimeout 一指令執行
CancellationToken 來電者請求取消非同步操作

逾時或取消並不能證明伺服器已回滾該項操作。 當多個變更必須作為一個單位提交或回滾時,使用交易,並根據操作的冪性與交易結果做出重試決策。

追蹤連線狀態

State 屬性會傳回 ConnectionState 列舉的快照。

State Meaning
Closed 邏輯連結並不開放。
Connecting 一場公開行動正在進行中。
Open 邏輯上的連結是開放的。

當狀態改變時,事件 StateChange 就會觸發。 其 StateChangeEventArgs 引數有兩個屬性:

  • OriginalState 是變化前的狀態。
  • CurrentState 是變更後的狀態。

驅動程式回報 Closed 到 Open 與 Open 到 Closed 的轉換,如 Open a connection 中的範例所示。 不要將觀察到的 Executing、Fetching 或 Broken 視為應用程式生命週期階段。

不要在每次指令前用 State 來做健康檢查。 網路在任何檢查後都可能故障。 執行該操作並處理產生的例外。 StateChange用於診斷,不是用於協調並行工作。

接收資訊性訊息

該 InfoMessage 事件會傳遞由伺服器傳送且不會引發錯誤的訊息。 這些訊息包括 PRINT 輸出訊息、 RAISERROR 嚴重度為 10 或以下的訊息,以及伺服器警告。 錯誤嚴重度為 11 或以上則會引發 SqlException。 關於嚴重程度等級,請參見 資料庫引擎 錯誤嚴重度。

事件處理器接收一個 SqlInfoMessageEventArgs 物件。 其 Errors 性質包含一組 SqlError 物件。 每一項都包含訊息號碼、文字、嚴重程度類別、程序及行號。

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString);
connection.InfoMessage += (_, e) =>
{
    foreach (SqlError error in e.Errors)
    {
        Console.WriteLine(
            $"Message {error.Number}, severity {error.Class}: {error.Message}");
    }
};

await connection.OpenAsync();

await using var command = new SqlCommand(
    """
    PRINT 'Starting the batch.';
    RAISERROR('Processed %d rows.', 10, 1, 42);
    """,
    connection);

await command.ExecuteNonQueryAsync();

輸出為:

Message 0, severity 0: Starting the batch.
Message 50000, severity 0: Processed 42 rows.

伺服器回報 RAISERROR 嚴重度為 10,等級為 0,因此 SqlError.Class 對於兩則訊息都顯示 0。

將使用者錯誤視為資訊訊息處理

預設情況下,驅動程式會透過拋出 SqlException 來回報嚴重性為 11 或更高的錯誤。 這個例外並不代表伺服器已停止該批次作業。 許多錯誤,包括 RAISERROR 嚴重度為 16 的錯誤,讓伺服器能執行剩餘的語句,因此即使你的程式碼捕捉到例外,後續的語句仍可能更改資料。 若要以訊息形式接收這些錯誤,而非例外,請設 FireInfoMessageEventOnUserErrors 為 true。 驅動程式則將嚴重性為 16 或以下的錯誤傳送至 InfoMessage事件,而非擲回例外。 這個特性改變了驅動程式回報錯誤的方式。 它不會改變伺服器執行哪些語句。

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString)
{
    FireInfoMessageEventOnUserErrors = true,
};
connection.InfoMessage += (_, e) =>
{
    foreach (SqlError error in e.Errors)
    {
        Console.WriteLine(
            $"Message {error.Number}, severity {error.Class}: {error.Message}");
    }
};

await connection.OpenAsync();

await using var command = new SqlCommand(
    """
    RAISERROR('Row 7 failed validation.', 16, 1);
    SELECT 'The batch continued.';
    """,
    connection);

await using (SqlDataReader reader = await command.ExecuteReaderAsync())
{
    do
    {
        while (await reader.ReadAsync())
        {
            Console.WriteLine(reader.GetString(0));
        }
    }
    while (await reader.NextResultAsync());
}

輸出為:

Message 50000, severity 16: Row 7 failed validation.
The batch continued.

錯誤嚴重度達17或以上,仍會拋出 SqlException,不論此設定如何。 啟用此屬性後,處理器負責偵測失敗。 預期每個錯誤都會有例外的程式碼,卻看不到例外。

回報應用程式識別資訊

自 Microsoft.Data.SqlClient 7.1.0 起,一個框架、工具或其他中介軟體可以回報是哪個應用程式開啟了連線。 在開啟連線前先設定 RegisteredApplication 一個 RegisteredApplication 數值。 驅動程式會在登入時將該數值傳送一次給伺服器。

請遵循以下規則:

  • 透過屬性設定數值。 沒有適用於它的 連接字串 關鍵字。
  • 在開啟連線前先設定好數值。 在連線正在開啟或已開啟時設定會擲回 InvalidOperationException 例外。
  • 把這個數值當作遙測數據來處理。 用戶端提供該值並可回報任何識別碼,因此伺服器不會驗證它。
  • 預期集區連線會回報原始身分。 該值不是池鍵的一部分。 從池中服務的連線會回報導致實體連線建立的邏輯連線的身份。

Caution

絕不要使用 RegisteredApplication 進行授權或任何其他安全決策。 任何客戶都可以回報任何識別碼。

選擇識別碼

預設值為 Unknown,即 0。 列舉的基礎類型為 ushort,因此識別碼範圍從 0 到 0xFFFF。

範圍 使用
0x0001 至 0x7FFF 由 Microsoft 定義的應用程式。 命名列舉成員使用此範圍。
0x8000 至 0xBFFF 僅供小規模使用。
0xC000 至 0xFFFF 公眾與開發者使用。

被命名的成員為 EntityFrameworkCore、 SemanticKernel、 ManagementStudio、 SqlManagementObjects、 EntityFramework、 AzureFunctionsSqlExtension、 DataTierApplicationFramework、 DurableTaskSqlServer、 SqlToolsService、 DataApiBuilder、 AspNetCoreDistributedSqlServerCache、 OrleansAdoNet,以及 SqlPackage。 若要報告沒有具名成員的識別項,請將該數字鑄造成 RegisteredApplication。

這個 RegisteredApplication 類型和屬性不符合 CLS,因為列舉用的是 ushort。 C# 程式碼可以直接使用它們。

設定識別碼

此程式會回報開發者範圍的識別碼,並顯示連線開啟後程式碼變更值時發生的狀況:

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString)
{
    RegisteredApplication = (RegisteredApplication)0xC001,
};

await connection.OpenAsync();
Console.WriteLine(
    $"Reported identifier: 0x{(ushort)connection.RegisteredApplication:X4}");

try
{
    connection.RegisteredApplication = RegisteredApplication.Unknown;
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
}

輸出為:

Reported identifier: 0xC001
InvalidOperationException: Not allowed to change the 'RegisteredApplication' property. The connection's current state is open.

了解池化效應

驅動程式只有在建立新的實體連線時才會回報識別碼。 啟用池化時:

  • 重複使用連線集區中的實體連線的連線會報告建立該實體連線的識別資訊,而非其自身的識別資訊。
  • 連接池在背景中開啟以滿足 Min Pool Size 的實體連線會報告 Unknown。

若一個 連接字串 供多個身分使用,則將報告值視為近似值。 當你需要精確歸因時,請關閉該 連接字串 的池化,並先測量額外的連線成本。

SqlConnection.Clone 將 RegisteredApplication 該值複製到新的連線。

不要同時分享連線

SqlConnection、SqlCommandSqlDataReaderSqlTransaction不支援多個執行緒同時使用。 讓每個並行操作各自使用自己的連線,並讓連線集區重複使用實體連線。

多重主動結果集(MARS)允許在支援的情境下,在同一連線上同時有多個主動批次。 它不會讓 SqlClient 物件成為執行緒安全,並且新增了會話和交易規則。 除非有特定操作需要,否則就保持關閉。

不要在相依性注入中將開放泛型 SqlConnection 註冊為單一實例。 註冊連線字串、不可變的選項物件,或可建立新連線的工廠。

審慎使用交易

本地交易屬於其連線。 交易中的每個指令都必須使用該連線並設定其 Transaction 屬性。

await using var connection = new SqlConnection(connectionString);
await connection.OpenAsync(cancellationToken);

await using SqlTransaction transaction =
    (SqlTransaction)await connection.BeginTransactionAsync(cancellationToken);

using var command = new SqlCommand(sql, connection, transaction);
command.Parameters.Add(
    new SqlParameter("@value", SqlDbType.Int) { Value = value });
await command.ExecuteNonQueryAsync(cancellationToken);

await transaction.CommitAsync(cancellationToken);

如果操作在提交前失敗,丟棄交易會回滾。 保持交易簡潔。 不要在資料庫交易還保留鎖時進行網路呼叫、使用者互動或無關的運算。

當 System.Transactions.Transaction.Current 啟用時,Open 和 OpenAsync 預設會自動加入。 僅在操作必須保持在環境交易之外時才設定 Enlist=false 。

測量一個邏輯連結

將 StatisticsEnabled 設為 true,以收集單一 SqlConnection 物件的驅動程式統計資料:

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

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString)
{
    StatisticsEnabled = true,
};

await connection.OpenAsync();
connection.ResetStatistics();

await using var command = new SqlCommand("SELECT name FROM sys.databases;", connection);
await using (SqlDataReader reader = await command.ExecuteReaderAsync())
{
    while (await reader.ReadAsync())
    {
    }
}

IDictionary statistics = connection.RetrieveStatistics();
Console.WriteLine($"ServerRoundtrips: {statistics["ServerRoundtrips"]}");
Console.WriteLine($"SelectRows: {statistics["SelectRows"]}");
Console.WriteLine($"BytesReceived > 0: {(long)statistics["BytesReceived"]! > 0}");

輸出顯示一趟往返。 列數取決於伺服器上的資料庫數量:

ServerRoundtrips: 1
SelectRows: 14
BytesReceived > 0: True

RetrieveStatistics 回傳快照。 ResetStatistics 開始新的測量邊界。 將StatisticsEnabled設為false,以停止收集。 目前收集的值仍然可取得。 統計是針對連線物件設定的,且會增加開銷,因此應啟用用於針對性診斷,而非每次生產請求。

處理連線失敗

在可記錄、轉譯或重試失敗作業的邊界處捕捉 SqlException。 紀錄:

  • Number
  • State
  • Class
  • ClientConnectionId
  • 操作名稱以及已設定的伺服器與資料庫識別碼

不要記錄連線字串、密碼、用戶端密碼或存取權杖。

釋放中斷的連線。 池子偵測到無效的實體連線時會移除它們。 如果憑證、憑證、憑證、DNS 目標或伺服器有變更,請在重試前先修正設定。

僅對暫態故障使用有界重試邏輯。 初始開啟重試、閒置連線恢復與指令重試是不同的機制。 更多資訊請參閱 可設定重試邏輯及 連線選項中的連線恢復選項。