命名Microsoft.Data.SqlClient空間包含支援的 .NET 資料提供者，適用於相容於 SQL Server 的資料庫。 它最初是從 System.Data.SqlClient 分支而來，並保留了大家熟悉的 ADO.NET 程式設計模型，同時可在不依賴 .NET 執行階段的情況下獨立推出新的 SQL Server 功能。
請使用 Microsoft.Data.SqlClient 進行新開發。
安裝並匯入命名空間
新增 NuGet 套件：
dotnet add package Microsoft.Data.SqlClient
匯入命名空間：
using Microsoft.Data.SqlClient;
大多數應用使用 SqlConnection、 SqlCommand、 SqlParameter、 SqlDataReader、 SqlTransaction和 。 完整公開表面，請參閱 Microsoft.Data.SqlClient API 參考資料。
與 ADO.NET 的關係
ADO.NET 是內建於 .NET 中的資料存取模型。 它在 System.Data.Common 命名空間中定義了提供者無關的抽象，而 Microsoft.Data.SqlClient 提供具體實作。
| ADO.NET 抽象化 | SqlClient 類型 | Purpose |
|---|---|---|
| DbConnection | SqlConnection | 建立與某個資料庫的邏輯連線。 |
| DbCommand | SqlCommand | 執行 Transact-SQL（T-SQL）文字或儲存程序。 |
| DbParameter | SqlParameter | 會將輸入值與命令文字分開傳送。 |
| DbDataReader | SqlDataReader | 從伺服器串流傳送結果資料列。 |
| DbTransaction | SqlTransaction | 將指令群組成一個交易，作為一個整體提交或回滾。 |
| DbDataAdapter | SqlDataAdapter | 填入並更新中斷連線的 DataSet 和 DataTable 物件。 |
| DbBatch | SqlBatch | 在支援的目標框架上，將多個指令作為一個批次發送。 |
Microsoft。Data.SqlClient 也提供 SQL Server 專用的 API，例如：
SqlBulkCopySqlConnectionStringBuilderSqlConfigurableRetryFactorySqlDependency- SQL Server 專屬的認證、加密與資料型別支援
當函式庫必須支援多個資料庫提供者時，應根據 ADO.NET 抽象層進行程式設計。 當應用程式針對 SQL Server 並需要提供者專屬功能（如 Microsoft Entra 認證、始終加密、批量複製、表值參數或可配置重試邏輯）時，請使用 SqlClient 類型。 如果應用程式其他部分必須保持提供者獨立，則將提供者專用程式碼保留在資料存取邊界後方。
連線與離線存取
連接式存取 在指令執行及應用程式讀取結果時，保持連線開啟。 典型的請求順序如下：
- 從一個連線字串建立
SqlConnection，然後將其開啟。 - 建立
SqlCommand並新增SqlParameter值。 - 執行 命令。
- 處理一個標量值、受影響的資料列數，或一個
SqlDataReader資料流。 - 釋放讀取器、命令和連線。
大多數網頁 API、服務、工作者及命令列應用程式都使用連網存取。
SqlDataReader 會以串流方式處理資料列，通常比將整個結果載入到 DataSet 中更省記憶體。
離線存取 使用 SqlDataAdapter 將資料複製到記憶體中的 DataSet 或 DataTable。 應用程式可以在讀取或更改記憶體資料時關閉連線，然後再重新連線以提交更新。 可以用它來綁定資料、記憶體內關係與約束、離線編輯後稍後再同步，或是圍繞 DataAdapters 建置的現有應用程式。 對於新的請求導向服務，請以 SqlCommand 和 SqlDataReader開頭。
物件壽命與並行性
為每個工作單位開立並釋放一個 SqlConnection。 連線池會重複使用底層的實體連線，因此不要讓一個全域連線在整個應用程式的整個生命週期內保持開啟。 迅速處置連線、指令、讀取器、交易及批量複製物件。 在非同步程式碼中，對於在目標框架上實作 SqlDataReader 的型別，請使用 IAsyncDisposable，例如 .NET 上的 SqlConnection 和 IDisposable；對於僅實作 using 的一般 await using 型別，則請使用 SqlBulkCopy。
SqlConnection、SqlCommand、SqlDataReader 和 SqlTransaction 不支援由多個執行緒同時使用。 讓每個並行作業各自使用自己的連線，並利用連線集區機制。 多重主動結果集（MARS）允許連線上有多個主動結果集，但並不保證 SqlClient 物件是執行緒安全的。
與 System.Data.SqlClient 的關係
System.Data.SqlClient是較早期的供應商，隨附 .NET Framework 及早期 .NET 版本。
Microsoft.Data.SqlClient 使用許多相同的類型名稱，但套件、命名空間、預設值、功能及支援政策不同。
不要在新的申請碼中提及兩個提供者。 兩個套件中同名的類型不能互換。 例如，當某處需要 Microsoft.Data.SqlClient.SqlConnection 時，就無法傳遞 System.Data.SqlClient.SqlConnection。
遷移通常從新增 Microsoft.Data.SqlClient 套件和更改命名空間參考開始，但你也必須檢視連線加密、參數、設定、傳遞依賴關係及執行時行為。 部署之前，請先參閱 從 System.Data.SqlClient 遷移至 Microsoft.Data.SqlClient。
版本相容性
驅動程式套件版本獨立於應用程式的 .NET 版本及資料庫引擎版本。 請勾選三項：
| Component | 需要驗證的項目 |
|---|---|
| Microsoft.Data.SqlClient | 此發布系列仍受支援，並包含您的應用程式所使用的功能。 |
| .NET 或 .NET 框架 | 該應用程式的目標執行階段受該驅動程式版本支援。 |
| SQL Server 相容資料庫 | 驅動程式版本支援資料庫版本，伺服器則支援任何要求的協定功能，例如 TDS 8.0。 |
關於目前的矩陣，請參見 SqlClient 驅動程式支援生命週期。
版本專屬變更
驅動程式版本可以新增 API、移動可選相依，並更改安全預設。 在每次大小更新前都要檢視變更。
範例包括：
- 版本 4.0 預設改
Encrypt為true。 - 5.0 版引入了用於 TDS 8.0 的
SqlConnectionEncryptOption和Encrypt=Strict。 - 版本 5.2 在支援的現代 .NET 目標上引入了
SqlBatch。 - 7.0 版本將驅動程式提供的 Microsoft Entra 認證移至
Microsoft.Data.SqlClient.Extensions.Azure。
請參閱 Microsoft.Data.SqlClient 的新功能，以取得發布說明連結及升級摘要。
相關命名空間與套件
部分功能使用主命名空間外的型別或選用套件。
| 命名空間或套件 | Purpose |
|---|---|
Microsoft.Data.SqlClient.Server |
SqlMetaData 與 SqlDataRecord 的 SqlClient 實作。 |
Microsoft.Data.SqlTypes |
SqlClient 專屬型別，例如 SqlFileStream、 SqlJson、 SqlVector<T>。 |
Microsoft.Data.SqlClient.Diagnostics |
強型別的診斷事件承載內容。 |
Microsoft.Data.SqlClient.Extensions.Azure |
驅動程式提供的 Microsoft Entra 認證，適用於 7.0 版本及以後版本。 |
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider |
Azure Key Vault 與 Always Encrypted 的整合 |
不要只從命名空間推斷套件需求。 請參考專題文章及你所使用驅動版本的 NuGet 套件相依性資訊。