Microsoft。Data.SqlClient 是支援 .NET 應用程式中新增 SQL Server 功能的提供者。 它保留了 System.Data.SqlClient所使用的 ADO.NET 程式設計模型，但在套件、命名空間、預設值及部分公開型別上有所不同。
把遷移當作提供者更新，而不只是命名空間的替換。
規劃移轉
在更改程式碼前：
記錄該應用程式支援的 .NET、
System.Data.SqlClientSQL Server 及 Microsoft SQL 服務版本。庫存驗證模式、連接字串 關鍵字、自訂憑證、Always Encrypted 提供者、
DbProviderFactories設定、SQL Server 使用者定義型別及System.Data.SqlTypes使用情況。執行應用程式目前的測試，並儲存連線、查詢、交易、重試及效能行為的基準。
搜尋直接和傳遞性套件參考：
dotnet list package --include-transitive
一次遷移一個應用程式或共享資料存取函式庫。 不要在仍使用 System.Data.SqlClient 的程式碼與使用 Microsoft.Data.SqlClient的程式碼之間傳遞提供者專用物件。
更換包裹
若有明確的 System.Data.SqlClient 套件參考，請將其移除：
dotnet remove package System.Data.SqlClient
新增 Microsoft。Data.SqlClient：
dotnet add package Microsoft.Data.SqlClient
如果 Microsoft.Data.SqlClient 7.0 或更新版本使用驅動程式提供的 Microsoft Entra 認證模式，也可新增：
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>
關於版本與套件選擇，請參見安裝、更新與部署 Microsoft。Data.SqlClient。
更新命名空間
替換主要提供者命名空間：
-using System.Data.SqlClient;
+using Microsoft.Data.SqlClient;
更新完全限定的名稱、別名、產生的程式碼、相依注入註冊、反射字串、配置，以及參考 System.Data.SqlClient的測試雙重。
不要取代一般的 System.Data 或 System.Data.Common 命名空間。
Microsoft.Data.SqlClient 繼續使用來自這些命名空間的 ADO.NET 類型，例如 CommandType、DbType、DbConnection、IsolationLevel、DataTable 和 DbCommand。
某些 SQL Server 專屬的命名空間類型會移動到其他Microsoft.Data命名空間：
| 類型 | 先前的命名空間 | Microsoft.Data.SqlClient 命名空間 |
|---|---|---|
SqlDataRecord、SqlMetaData |
Microsoft.SqlServer.Server |
Microsoft.Data.SqlClient.Server |
SqlFileStream |
System.Data.SqlTypes |
Microsoft.Data.SqlTypes |
SqlNotificationRequest |
System.Data.Sql |
Microsoft.Data.Sql |
OperationAbortedException |
System.Data |
Microsoft.Data |
在 Microsoft.Data.SqlClient 5.0 及以後版本中，其他 SQL Server 通用語言執行時（CLR）類型仍保留在 Microsoft.SqlServer.Server。 根據編譯器錯誤和 Microsoft.Data.SqlClient API 參考文件 更新每個型別，而不是取代整個命名空間。
更新 .NET Framework 設定
透過 DbProviderFactories 解析提供者的應用程式，可能需要在 App.config 或 Web.config 中註冊提供者：
<configuration>
<system.data>
<DbProviderFactories>
<add name="SqlClient Data Provider"
invariant="Microsoft.Data.SqlClient"
description=".NET data provider for SQL Server"
type="Microsoft.Data.SqlClient.SqlClientFactory, Microsoft.Data.SqlClient" />
</DbProviderFactories>
</system.data>
</configuration>
更新請求提供者不變名稱的程式碼：
DbProviderFactory factory =
DbProviderFactories.GetFactory("Microsoft.Data.SqlClient");
當應用程式直接建立 SqlConnection 且不使用 DbProviderFactories時，不要新增這個設定。
檢視加密與憑證驗證
Microsoft。Data.SqlClient 使用比 System.Data.SqlClient 更安全的預設值。
| 行為 | System.Data.SqlClient | Microsoft.Data.SqlClient |
|---|---|---|
| 預設加密 | Encrypt=false |
Encrypt=true 從 4.0 版本開始 |
| 伺服器憑證驗證 | 只有在啟用用戶端加密時才驗證憑證 | 從 2.0 版開始，當伺服器強制加密時，會根據 TrustServerCertificate 驗證憑證，即使 Encrypt=false |
| 嚴格加密 | 不支援 |
Encrypt=Strict 自 5.0 版起，適用於支援 TDS 8.0 的伺服器 |
SqlConnectionStringBuilder.Encrypt 類型 |
bool |
SqlConnectionEncryptOption 從 5.0 版本開始 |
不要將 Encrypt=false 或 TrustServerCertificate=true 設為通用的遷移修正方式。 設定一個客戶端信任的憑證，並使用與該憑證相符的伺服器名稱。 僅在無法進行驗證的受控開發環境中使用 TrustServerCertificate=true。
這個 SqlConnectionEncryptOption 變更在常見指派中透過隱式轉換與原始碼相容，但這是二元破壞性的變更。 重新編譯所有會存取 SqlConnectionStringBuilder.Encrypt 的組件。
如需詳細資訊，請參閱加密和憑證驗證。
檢閱連接字串
Microsoft。Data.SqlClient 會加入 System.Data.SqlClient 無法辨識的關鍵字和別名。 例如，它接受包含空格的別名，例如 Application Intent 和 Multi Subnet Failover。
不要用 Microsoft.Data.SqlClient.SqlConnectionStringBuilder 建立連線字串，然後再將它傳給 System.Data.SqlClient。 在分階段遷移過程中，請讓每個連線字串建構器都與其提供者配對使用。
對照 連接字串語法，檢閱驗證、加密、重試、容錯移轉和憑證關鍵字。
檢視參數行為
測試日期與時間參數明確說明：
| 參數 | System.Data.SqlClient 行為 | Microsoft.Data.SqlClient 行為 |
|---|---|---|
DbType.Time值為DateTime |
接受該值 | 使用一個 TimeSpan 數值 |
DbType.Date值為DateTime |
可以傳送日期和時間成分 | 截去時間部分 |
在 SQL Server 類型推論可能改變查詢計畫或轉換行為的參數中，指定 SqlDbType、 長度、精確度與縮放。 當資料庫類型已知時，不要把 AddWithValue 它當作遷移捷徑。
檢查傳遞性提供者參照
直接移除套件並不能保證 System.Data.SqlClient 已消失。 跑步：
dotnet list package --include-transitive
如果兩個供應商都繼續存在：
- 找出引入
System.Data.SqlClient的套件。 - 如果可能，更新或替換那個依賴。
- 當兩者都必須保留時，請將特定提供者的型別保留在依賴邊界內。
- 僅將明確的命名空間別名作為暫時輔助。 不要將連線、交易、參數或讀取器從一個提供者傳遞給另一個提供者。
特別要注意 SQL Server 的 CLR 類型函式庫，以及在公開 API 中暴露System.Data.SqlClient型態的舊資料存取框架。
回顧全球化行為
.NET Framework 及 .NET 5 之前的 .NET 版本在 Windows 上採用國家語言支援（NLS）全球化。 目前的 .NET 版本預設使用 Unicode 國際元件（ICU），適用於 Windows、Linux 和 macOS。
這種執行階段差異可能會改變某些 SqlString 比較的結果。 SQL Server 使用 NLS 比較行為。 如果用戶端 SqlString 比較必須符合伺服器端的行為，請測試受影響的值，並參閱 全球化與 ICU。 應用程式在需要時 可使用 NLS 取代 ICU 。
Microsoft.Data.SqlClient 不支援全球化不變模式。
驗證遷移後的應用程式
在每個支援的目標框架和作業系統上建置並測試。
驗證：
- 套件還原並發佈輸出。
- SQL 認證、Windows 整合認證，以及應用程式使用的 Microsoft Entra 認證。
- TLS 協商、憑證驗證與 連接字串 解析。
- 連線集區與存取權杖重新整理。
- 參數類型、空值、精確度、縮放、日期和時間行為。
- 交易、取消、超時、重試和故障轉移。
- Always Encrypted、SQL Server CLR 類型、批量複製、查詢通知，以及應用程式使用的其他提供者專屬功能。
- 日誌記錄、計數器、追蹤和異常處理。
對每個支援的資料庫引擎版本執行代表性查詢。 成功的編譯並不代表驗證連線安全性、執行時相依性或資料轉換。