從 EF6 移植至 EF Core

  • 發行項

Entity Framework Core (或簡稱為 EF Core) 是徹底重寫的新式應用程式架構 Entity Framework。 因為是從根本變更，所以沒有直接升級路徑。 本文件的目的是提供將 EF6 應用程式移植到 EF Core 的端對端指南。

重要

在開始移植程序之前，請務必確認 EF Core 符合應用程式的資料存取需求。 您可以在 EF Core 文件中找到所需的一切。

重要

可攜性分析器已知問題 (microsoft/dotnet-apiport #993)：錯誤回報 EF Core 與 .NET 5 和 .NET 6 不相容。 您可以忽略這些警告，沒有安全性顧慮，因為 EF Core 與 .NET 5 和 .NET 6 目標架構 100% 相容。

升級的原因

EF Core 具備所有新的 Entity Framework 開發。 沒有將任何新功能向後移植到 EF6 的方案。 EF Core 會在最新的 .NET 執行階段中執行，充分利用執行階段、平台特定 (例如 ASP.NET Core或 WPF) 和語言特定的功能。 以下是升級的幾個優點：

  • 利用 EF Core 的持續效能改善。 例如，從 EF6 移轉至 EF Core 6 的客戶，因為查詢分割功能，大量查詢的用量可減少 40 倍。 許多客戶回報，只要移至最新的 EF Core，就能大幅提升效能。
  • 使用 EF Core 的新功能。 EF6 將不會新增任何新功能。 所有新功能，例如 Azure Cosmos DB 提供者和 DbContextFactory，都只會新增到 EF Core。 如需 EF6 與 EF Core 的完整比較，包括 EF Core 專屬的數個功能，請參閱： 比較 EF Core 和 EF6。
  • 使用相依性插入將應用程式堆疊現代化，並緊密整合資料存取與 gRPC 和 GraphQL 等技術。

移轉注意事項

本文件使用「移植」和「升級」等詞，以免與 EF Core 功能的「移轉」一詞混淆。 EF Core 的移轉因大幅改善了移轉的處理方式，所以與 EF6 Code First 移轉不相容。 沒有移植移轉歷程記錄的建議方法，因此請規劃在 EF Core 中「全新」開始。 您可以維護 EF6 移轉的程式碼基底和資料。 在 EF6 中套用最終移轉，然後在 EF Core 中建立初始移轉。 您就可以追蹤 EF Core 的歷程記錄。

升級步驟

升級路徑已分割成數份文件，依照您的升級階段和應用程式類型組織。

決定您的 EF Core「變體」

有數種方法可讓 EF Core 搭配領域模型和資料庫實作運作。 一般而言，大多數的應用程式會遵循下列其中一種模式，而您完成移植的方式則取決於應用程式「變體」。

程式碼為事實來源這種方法，會透過程式碼和類別將所有項目模型化，無論是透過資料屬性、Fluent 設定，還是兩者的組合。 資料庫一開始是根據 EF Core 中定義的模型產生，而進一步的更新一般則是透過移轉處理。 這通常稱為 "Code First"，但這個名稱不完全正確，因為有一種方法是從現有的資料庫開始、產生實體，然後靠著程式碼繼續作業。

資料庫為事實來源的方法，涉及反向工程或從資料庫建立程式碼結構。 完成結構描述變更後，會重新產生或更新程式碼以反映變更。 這通常稱為 "Database First"。

最後，則是更進階的混合式對應方法，此方法遵循程式碼和資料庫分開管理的原則，使用 EF Core 對應這兩者。 這種方法一般會避開移轉。

下表摘要說明一些大概的差異：

方法 開發人員角色 DBA 角色 移轉 Scaffolding 存放庫
Code First 設計實體以及驗證/自訂產生的移轉 驗證結構描述定義和變更 依認可 N/A 追蹤實體、DbCoNtext 和移轉
Database First 變更後進行反向工程，並驗證產生的實體 當資料庫變更為重新建構時通知開發人員 N/A 依結構描述變更 追蹤可擴充所產生實體的延伸模組/部分類別
混合式 更新 Fluent 設定以對應每次的實體或資料庫變更 當資料庫變更時通知開發人員，以便其可更新實體和模型設定 N/A N/A 追蹤實體和 DbCoNtext

相較於傳統的程式碼和資料庫方法，混合式方法是具有多了額外負荷的更進階方法。

了解離開 EDMX 的影響

EF6 以前支援名為「實體資料模型 XML (EDMX)」的特殊模型定義格式。 EDMX 檔案包含多個定義，包括概念結構描述定義 (CSDL)、對應規格 (MSL)，以及將存放結構描述定義 (SSDL)。 EF Core 透過內部模型圖形追蹤領域、對應和資料庫結構描述，但不支援 EDMX 格式。 許多部落格貼文和文章誤指這表示 EF Core 僅支援 "code first"。EF Core 支援上節所述的全部三個應用程式模型。 您可以執行資料庫反向工程，在 EF Core 中重建模型。 如果您使用 EDMX 呈現實體模型的視覺效果，請考慮使用提供 EF Core 類似功能的開放原始碼 EF Core Power Tools。

如需因缺少 EDMX 檔案支援所受影響的詳細資訊，請參閱移植 EDMX 指南。

執行升級步驟

不需要移植整個應用程式。 EF6 和 EF Core 可以在相同的應用程式中執行 (請參閱：在相同的應用程式中使用 EF Core 和 EF6)。 若要將風險降到最低，您可能要考慮：

  1. 如果尚未移至 .NET Core 上的 EF6，請移過去。
  2. 將應用程式的一小部分移轉至 EF Core，並與 EF6 並排執行。
  3. 最後，將其餘的程式碼基底帶入 EF Core，然後淘汰 EF6 程式碼。

至於移植本身，概括而言，您要：

  1. 檢閱 EF6 與 EF Core 之間的行為變更。
  2. 在 EF6 中執行最終移轉 (如有)。
  3. 建立 EF Core 專案。
  4. 將程式碼複製到新專案、執行反向工程或兩者的組合。
  5. 重新命名參考和實體，並更新行為：
    • 按 System.Data.Entity 移至 Microsoft.EntityFrameworkCore
    • 變更 DbContext 建構函式以取用選項及/或覆寫 OnConfiguring
    • 按 DbModelBuilder 移至 ModelBuilder
    • 將 DbEntityEntry<T> 重新命名為 EntityEntry<T>
    • 從 Database.Log 移至 Microsoft.Extensions.Logging (進階) 或移至 DbContextOptionsBuilder.LogTo (簡單) API
    • 套用 WithRequired 和 WithOptional 的變更 (請參閱這裡)
    • 更新驗證碼。 EF Core 中沒有內建的資料驗證，但您可以自行建立。
    • 請依照任何必要的步驟從 EDMX 移植。
  6. 根據您的 EF Core 方法執行特定步驟：

有許多和全部方法相關的考慮，因此您也會想要檢閱可以解決及因應 EF6 與 EF Core 間詳細差異的方法。