EF Core 8 的新功能

EF Core 8.0 （EF8） 於 2023 年 11 月發行。

EF8 需要 .NET 8 SDK 才能建置，而且需要 .NET 8 運行時間才能執行。 EF8 不會在舊版 .NET 上執行，也不會在 .NET Framework 上執行。

使用複雜型別的值物件

儲存至資料庫的物件可以分割成三大類別：

• 非結構化物件並保留單一值。 例如，、int、Guidstring、 IPAddress。 這些稱為「基本類型」（有點鬆散）。
• 結構化來保存多個值的物件，以及對象的識別是由索引鍵值所定義的位置。 例如，Blog、Post、Customer。 這些稱為「實體類型」。
• 結構化來保存多個值的物件，但對象沒有定義識別的索引鍵。 例如，Address、Coordinate。

在 EF8 之前，無法對應第三種類型的物件。 可以使用擁有的類型，但因為擁有的類型 實際上是實體類型，所以即使隱藏了該索引鍵值，它們也有以索引鍵值為基礎的語意。

EF8 現在支援「複雜類型」，以涵蓋這個第三種類型的物件。 複雜類型物件：

• 索引鍵值無法識別或追蹤。
• 必須定義為實體類型的一部分。 （換句話說，您不能有 DbSet 複雜類型的 。
• 可以是 .NET 實值型 別或 參考型別。
• 實例可以由多個屬性共用。

簡單範例

例如，請考慮類型 Address ：

public class Address
{
    public required string Line1 { get; set; }
    public string? Line2 { get; set; }
    public required string City { get; set; }
    public required string Country { get; set; }
    public required string PostCode { get; set; }
}

Address 然後在簡單的客戶/訂單模型中，在三個地方使用：

public class Customer
{
    public int Id { get; set; }
    public required string Name { get; set; }
    public required Address Address { get; set; }
    public List<Order> Orders { get; } = new();
}

public class Order
{
    public int Id { get; set; }
    public required string Contents { get; set; }
    public required Address ShippingAddress { get; set; }
    public required Address BillingAddress { get; set; }
    public Customer Customer { get; set; } = null!;
}

讓我們使用其位址來建立並儲存客戶：

var customer = new Customer
{
    Name = "Willow",
    Address = new() { Line1 = "Barking Gate", City = "Walpole St Peter", Country = "UK", PostCode = "PE14 7AV" }
};

context.Add(customer);
await context.SaveChangesAsync();

這會導致下列資料列插入資料庫中：

INSERT INTO [Customers] ([Name], [Address_City], [Address_Country], [Address_Line1], [Address_Line2], [Address_PostCode])
OUTPUT INSERTED.[Id]
VALUES (@p0, @p1, @p2, @p3, @p4, @p5);

請注意，複雜型別不會取得自己的數據表。 相反地，它們會內嵌儲存至數據表的數據 Customers 行。 這符合擁有類型的數據表共享行為。

現在，假設我們想要將訂單寄送給客戶，並使用客戶的位址作為出貨位址的預設帳單。 這樣做的自然方式是將 物件從 Customer Order複製到 Address 。 例如：

customer.Orders.Add(
    new Order { Contents = "Tesco Tasty Treats", BillingAddress = customer.Address, ShippingAddress = customer.Address, });

await context.SaveChangesAsync();

使用複雜類型時，這會如預期般運作，並將位址插入 Orders 數據表中：

INSERT INTO [Orders] ([Contents], [CustomerId],
    [BillingAddress_City], [BillingAddress_Country], [BillingAddress_Line1], [BillingAddress_Line2], [BillingAddress_PostCode],
    [ShippingAddress_City], [ShippingAddress_Country], [ShippingAddress_Line1], [ShippingAddress_Line2], [ShippingAddress_PostCode])
OUTPUT INSERTED.[Id]
VALUES (@p0, @p1, @p2, @p3, @p4, @p5, @p6, @p7, @p8, @p9, @p10, @p11);

到目前為止，你可能會說，「但我可以用擁有的類型做到這一點！不過，擁有型別的「實體類型」語意很快就會妨礙。 例如，以擁有的類型執行上述程式代碼會導致大量警告，然後產生錯誤：

warn: 8/20/2023 12:48:01.678 CoreEventId.DuplicateDependentEntityTypeInstanceWarning[10001] (Microsoft.EntityFrameworkCore.Update) 
      The same entity is being tracked as different entity types 'Order.BillingAddress#Address' and 'Customer.Address#Address' with defining navigations. If a property value changes, it will result in two store changes, which might not be the desired outcome.
warn: 8/20/2023 12:48:01.687 CoreEventId.DuplicateDependentEntityTypeInstanceWarning[10001] (Microsoft.EntityFrameworkCore.Update) 
      The same entity is being tracked as different entity types 'Order.ShippingAddress#Address' and 'Customer.Address#Address' with defining navigations. If a property value changes, it will result in two store changes, which might not be the desired outcome.
warn: 8/20/2023 12:48:01.687 CoreEventId.DuplicateDependentEntityTypeInstanceWarning[10001] (Microsoft.EntityFrameworkCore.Update)
      The same entity is being tracked as different entity types 'Order.ShippingAddress#Address' and 'Order.BillingAddress#Address' with defining navigations. If a property value changes, it will result in two store changes, which might not be the desired outcome.
fail: 8/20/2023 12:48:01.709 CoreEventId.SaveChangesFailed[10000] (Microsoft.EntityFrameworkCore.Update) 
      An exception occurred in the database while saving changes for context type 'NewInEfCore8.ComplexTypesSample+CustomerContext'.
      System.InvalidOperationException: Cannot save instance of 'Order.ShippingAddress#Address' because it is an owned entity without any reference to its owner. Owned entities can only be saved as part of an aggregate also including the owner entity.
         at Microsoft.EntityFrameworkCore.ChangeTracking.Internal.InternalEntityEntry.PrepareToSave()

這是因為實體類型的單一實例 Address （具有相同的隱藏索引鍵值）正用於三 個不同的 實體實例。 另一方面，允許在複雜屬性之間共用相同的實例，因此當使用複雜類型時，程式代碼會如預期般運作。

複雜類型的設定

複雜型別必須在模型中使用對應屬性或在 中OnModelCreating呼叫 API 來設定ComplexProperty。 依慣例不會探索複雜型別。

例如， Address 可以使用 來設定 ComplexTypeAttribute類型：

[ComplexType]
public class Address
{
    public required string Line1 { get; set; }
    public string? Line2 { get; set; }
    public required string City { get; set; }
    public required string Country { get; set; }
    public required string PostCode { get; set; }
}

或在 中 OnModelCreating：

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Customer>()
        .ComplexProperty(e => e.Address);

    modelBuilder.Entity<Order>(b =>
    {
        b.ComplexProperty(e => e.BillingAddress);
        b.ComplexProperty(e => e.ShippingAddress);
    });
}

可變動性

在上述範例中，我們最終使用了三個位置所使用的相同 Address 實例。 這是允許的，而且在使用複雜類型時不會對EF Core造成任何問題。 不過，共用相同參考類型的實例表示，如果修改實例上的屬性值，則該變更將會反映在這三種用法中。 例如，遵循上述內容，讓我們變更 Line1 客戶位址並儲存變更：

customer.Address.Line1 = "Peacock Lodge";
await context.SaveChangesAsync();

這會導致使用 SQL Server 時，對資料庫進行下列更新：

UPDATE [Customers] SET [Address_Line1] = @p0
OUTPUT 1
WHERE [Id] = @p1;
UPDATE [Orders] SET [BillingAddress_Line1] = @p2, [ShippingAddress_Line1] = @p3
OUTPUT 1
WHERE [Id] = @p4;

請注意，這三 Line1 個數據行都已變更，因為它們全都共用相同的實例。 這通常不是我們想要的。

處理這類問題的好方法，就是讓類型不可變。 事實上，當類型是複雜類型的好候選專案時，這種不變性通常很自然。 例如，通常提供複雜的新 Address 物件，而不是只改變國家/地區，同時讓其餘部分保持不變是合理的。

參考和實值型別都可以不可變。 我們將在下列各節中查看一些範例。

將型別參考為複雜型別

不可變類別

我們在上述範例中使用了簡單且可變的 class 。 為了防止上述意外突變的問題，我們可以讓 類別不可變。 例如：

public class Address
{
    public Address(string line1, string? line2, string city, string country, string postCode)
    {
        Line1 = line1;
        Line2 = line2;
        City = city;
        Country = country;
        PostCode = postCode;
    }

    public string Line1 { get; }
    public string? Line2 { get; }
    public string City { get; }
    public string Country { get; }
    public string PostCode { get; }
}

public class Address(string line1, string? line2, string city, string country, string postCode)
{
    public string Line1 { get; } = line1;
    public string? Line2 { get; } = line2;
    public string City { get; } = city;
    public string Country { get; } = country;
    public string PostCode { get; } = postCode;
}

現在無法變更 Line1 現有位址上的值。 相反地，我們需要建立具有已變更值的新實例。 例如：

var currentAddress = customer.Address;
customer.Address = new Address(
    "Peacock Lodge", currentAddress.Line2, currentAddress.City, currentAddress.Country, currentAddress.PostCode);

await context.SaveChangesAsync();

這次呼叫 SaveChangesAsync 只會更新客戶位址：

UPDATE [Customers] SET [Address_Line1] = @p0
OUTPUT 1
WHERE [Id] = @p1;

請注意，即使 Address 物件不可變，而且整個物件已變更，EF 仍會追蹤個別屬性的變更，因此只會更新具有變更值的數據行。

不可變的記錄

C# 9 引進 了記錄類型，可讓建立和使用不可變的物件變得更容易。 例如， Address 物件可以建立記錄類型：

public record Address
{
    public Address(string line1, string? line2, string city, string country, string postCode)
    {
        Line1 = line1;
        Line2 = line2;
        City = city;
        Country = country;
        PostCode = postCode;
    }

    public string Line1 { get; init; }
    public string? Line2 { get; init; }
    public string City { get; init; }
    public string Country { get; init; }
    public string PostCode { get; init; }
}

public record Address(string Line1, string? Line2, string City, string Country, string PostCode);

取代可變物件並呼叫 SaveChanges 現在需要較少的程式代碼：

customer.Address = customer.Address with { Line1 = "Peacock Lodge" };

await context.SaveChangesAsync();

實值型別做為複雜型別

可變結構

簡單的可變 實值型 別可用來做為複雜型別。 例如， Address 可以在 C# 中定義為 struct ：

public struct Address
{
    public required string Line1 { get; set; }
    public string? Line2 { get; set; }
    public required string City { get; set; }
    public required string Country { get; set; }
    public required string PostCode { get; set; }
}

將客戶 Address 物件指派給出貨和計費 Address 屬性會導致每個屬性取得 的 Address複本，因為這是實值類型的運作方式。 這表示修改 Address 客戶上的 不會變更出貨或計費 Address 實例，因此可變結構不會有與可變動類別發生的相同實例共享問題。

不過， C# 通常不建議使用可變結構，因此請在使用結構之前仔細思考。

不可變結構

不可變結構的運作方式與複雜類型相同，就像不可變的類別一樣。 例如， Address 可以定義，使其無法修改：

public readonly struct Address(string line1, string? line2, string city, string country, string postCode)
{
    public string Line1 { get; } = line1;
    public string? Line2 { get; } = line2;
    public string City { get; } = city;
    public string Country { get; } = country;
    public string PostCode { get; } = postCode;
}

變更位址的程式代碼現在看起來與使用不可變類別時相同：

var currentAddress = customer.Address;
customer.Address = new Address(
    "Peacock Lodge", currentAddress.Line2, currentAddress.City, currentAddress.Country, currentAddress.PostCode);

await context.SaveChangesAsync();

不可變的結構記錄

C# 10 引進 struct record 的類型，可讓您輕鬆地建立和使用不可變的結構記錄，就像是使用不可變的類別記錄一樣。 例如，我們可以將 定義為 Address 不可變的結構記錄：

public readonly record struct Address(string Line1, string? Line2, string City, string Country, string PostCode);

變更位址的程式代碼現在看起來與使用不可變類別記錄時相同：

customer.Address = customer.Address with { Line1 = "Peacock Lodge" };

await context.SaveChangesAsync();

巢狀複雜類型

複雜類型可以包含其他複雜類型的屬性。 例如，讓我們將 Address 上述的複雜類型與複雜類型一起使用，並將兩者巢狀於另一個 PhoneNumber 複雜類型內：

public record Address(string Line1, string? Line2, string City, string Country, string PostCode);

public record PhoneNumber(int CountryCode, long Number);

public record Contact
{
    public required Address Address { get; init; }
    public required PhoneNumber HomePhone { get; init; }
    public required PhoneNumber WorkPhone { get; init; }
    public required PhoneNumber MobilePhone { get; init; }
}

我們在這裡使用不可變的記錄，因為這些是適合複雜型別語意的相符專案，但複雜類型的巢狀化可以使用任何 .NET 類型的類別來完成。

我們會將 新增 Contact 為 的 Customer屬性：

public class Customer
{
    public int Id { get; set; }
    public required string Name { get; set; }
    public required Contact Contact { get; set; }
    public List<Order> Orders { get; } = new();
}

與 PhoneNumber 作為屬性 Order：

public class Order
{
    public int Id { get; set; }
    public required string Contents { get; set; }
    public required PhoneNumber ContactPhone { get; set; }
    public required Address ShippingAddress { get; set; }
    public required Address BillingAddress { get; set; }
    public Customer Customer { get; set; } = null!;
}

您可以再次使用 ComplexTypeAttribute來設定巢狀複雜型別：

[ComplexType]
public record Address(string Line1, string? Line2, string City, string Country, string PostCode);

[ComplexType]
public record PhoneNumber(int CountryCode, long Number);

[ComplexType]
public record Contact
{
    public required Address Address { get; init; }
    public required PhoneNumber HomePhone { get; init; }
    public required PhoneNumber WorkPhone { get; init; }
    public required PhoneNumber MobilePhone { get; init; }
}

或在 中 OnModelCreating：

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Customer>(
        b =>
        {
            b.ComplexProperty(
                e => e.Contact,
                b =>
                {
                    b.ComplexProperty(e => e.Address);
                    b.ComplexProperty(e => e.HomePhone);
                    b.ComplexProperty(e => e.WorkPhone);
                    b.ComplexProperty(e => e.MobilePhone);
                });
        });

    modelBuilder.Entity<Order>(
        b =>
        {
            b.ComplexProperty(e => e.ContactPhone);
            b.ComplexProperty(e => e.BillingAddress);
            b.ComplexProperty(e => e.ShippingAddress);
        });
}

查詢

實體類型上複雜型別的屬性會被視為實體類型的任何其他非導覽屬性。 這表示載入實體類型時，一律會載入它們。 這也適用於任何巢狀複雜類型屬性。 例如，查詢客戶：

var customer = await context.Customers.FirstAsync(e => e.Id == customerId);

使用 SQL Server 時，會轉譯成下列 SQL：

SELECT TOP(1) [c].[Id], [c].[Name], [c].[Contact_Address_City], [c].[Contact_Address_Country],
    [c].[Contact_Address_Line1], [c].[Contact_Address_Line2], [c].[Contact_Address_PostCode],
    [c].[Contact_HomePhone_CountryCode], [c].[Contact_HomePhone_Number], [c].[Contact_MobilePhone_CountryCode],
    [c].[Contact_MobilePhone_Number], [c].[Contact_WorkPhone_CountryCode], [c].[Contact_WorkPhone_Number]
FROM [Customers] AS [c]
WHERE [c].[Id] = @__customerId_0

請注意此 SQL 的兩件事：

• 所有項目都會傳回，以填入客戶 和 所有巢狀 Contact、 Address和 PhoneNumber 複雜類型。
• 所有複雜類型值都會儲存為實體類型數據表中的數據行。 複雜型別永遠不會對應至個別的數據表。

投影

複雜類型可以從查詢投影。 例如，只從訂單選取出貨位址：

var shippingAddress = await context.Orders
    .Where(e => e.Id == orderId)
    .Select(e => e.ShippingAddress)
    .SingleAsync();

使用 SQL Server 時，這會轉譯為下列內容：

SELECT TOP(2) [o].[ShippingAddress_City], [o].[ShippingAddress_Country], [o].[ShippingAddress_Line1],
    [o].[ShippingAddress_Line2], [o].[ShippingAddress_PostCode]
FROM [Orders] AS [o]
WHERE [o].[Id] = @__orderId_0

請注意，無法追蹤複雜類型的投影，因為複雜類型對象沒有用於追蹤的身分識別。

在述詞中使用

複雜型別的成員可用於述詞中。 例如，尋找前往特定城市的所有訂單：

var city = "Walpole St Peter";
var walpoleOrders = await context.Orders.Where(e => e.ShippingAddress.City == city).ToListAsync();

這會轉譯為 SQL Server 上的下列 SQL：

SELECT [o].[Id], [o].[Contents], [o].[CustomerId], [o].[BillingAddress_City], [o].[BillingAddress_Country],
    [o].[BillingAddress_Line1], [o].[BillingAddress_Line2], [o].[BillingAddress_PostCode],
    [o].[ContactPhone_CountryCode], [o].[ContactPhone_Number], [o].[ShippingAddress_City],
    [o].[ShippingAddress_Country], [o].[ShippingAddress_Line1], [o].[ShippingAddress_Line2],
    [o].[ShippingAddress_PostCode]
FROM [Orders] AS [o]
WHERE [o].[ShippingAddress_City] = @__city_0

完整複雜型別實例也可用於述詞中。 例如，尋找具有指定電話號碼的所有客戶：

var phoneNumber = new PhoneNumber(44, 7777555777);
var customersWithNumber = await context.Customers
    .Where(
        e => e.Contact.MobilePhone == phoneNumber
             || e.Contact.WorkPhone == phoneNumber
             || e.Contact.HomePhone == phoneNumber)
    .ToListAsync();

這會在使用 SQL Server 時轉譯為下列 SQL：

SELECT [c].[Id], [c].[Name], [c].[Contact_Address_City], [c].[Contact_Address_Country], [c].[Contact_Address_Line1],
     [c].[Contact_Address_Line2], [c].[Contact_Address_PostCode], [c].[Contact_HomePhone_CountryCode],
     [c].[Contact_HomePhone_Number], [c].[Contact_MobilePhone_CountryCode], [c].[Contact_MobilePhone_Number],
     [c].[Contact_WorkPhone_CountryCode], [c].[Contact_WorkPhone_Number]
FROM [Customers] AS [c]
WHERE ([c].[Contact_MobilePhone_CountryCode] = @__entity_equality_phoneNumber_0_CountryCode
    AND [c].[Contact_MobilePhone_Number] = @__entity_equality_phoneNumber_0_Number)
OR ([c].[Contact_WorkPhone_CountryCode] = @__entity_equality_phoneNumber_0_CountryCode
    AND [c].[Contact_WorkPhone_Number] = @__entity_equality_phoneNumber_0_Number)
OR ([c].[Contact_HomePhone_CountryCode] = @__entity_equality_phoneNumber_0_CountryCode
    AND [c].[Contact_HomePhone_Number] = @__entity_equality_phoneNumber_0_Number)

請注意，相等是藉由展開複雜類型的每個成員來執行。 這與沒有身分識別索引鍵的複雜型別一致，因此複雜型別實例只有在所有成員都相等時，才會等於另一個複雜類型實例。 這也符合 .NET 針對記錄類型所定義的相等性。

操作複雜類型值

EF8 可讓您存取追蹤資訊，例如複雜型別的目前和原始值，以及是否已修改屬性值。 API 複雜類型是已用於實體類型之變更追蹤 API 的延伸模組。

傳 ComplexProperty 回整個複雜物件之專案的方法 EntityEntry 。 例如，若要取得 的目前值 Order.BillingAddress：

var billingAddress = context.Entry(order)
    .ComplexProperty(e => e.BillingAddress)
    .CurrentValue;

您可以新增 對 Property 的呼叫，以存取複雜類型的屬性。 例如，只取得帳單後代碼的目前值：

var postCode = context.Entry(order)
    .ComplexProperty(e => e.BillingAddress)
    .Property(e => e.PostCode)
    .CurrentValue;

巢狀複雜類型是使用 對 ComplexProperty的巢狀呼叫來存取。 例如，若要從 上的Customer巢狀 Address Contact 取得城市：

var currentCity = context.Entry(customer)
    .ComplexProperty(e => e.Contact)
    .ComplexProperty(e => e.Address)
    .Property(e => e.City)
    .CurrentValue;

其他方法可用於讀取和變更狀態。 例如， PropertyEntry.IsModified 可以用來將複雜類型的屬性設定為已修改：

context.Entry(customer)
    .ComplexProperty(e => e.Contact)
    .ComplexProperty(e => e.Address)
    .Property(e => e.PostCode)
    .IsModified = true;

目前的限制

複雜類型代表跨EF堆疊進行大量投資。 我們無法讓此版本的所有專案都能夠運作，但我們計劃在未來版本中關閉一些差距。 修正上述任何限制對於您而言很重要，請務必對適當的 GitHub 問題進行投票👍。

EF8 中的複雜類型限制包括：

• 支援複雜類型的集合。 （問題 #31237）
• 允許複雜類型屬性為 Null。 （問題 #31376）
• 將複雜類型屬性對應至 JSON 資料行。 （問題 #31252）
• 複雜類型的建構函式插入。 （問題 #31621）
• 新增複雜類型的種子數據支援。 （問題 #31254）
• 對應 Cosmos 提供者的複雜類型屬性。 （問題 #31253）
• 實作記憶體內部資料庫的複雜類型。 （問題 #31464）

基本集合

使用關係資料庫時的持續性問題，就是使用基本類型集合時要執行的動作;也就是整數、日期/時間、字串等等的清單或陣列。 如果您使用PostgreSQL，則很容易使用PostgreSQL的 內建數位型態來儲存這些專案。 對於其他資料庫，有兩種常見的方法：

• 使用基本類型值的數據行和另一個數據行建立數據表，以做為外鍵，將每個值連結到集合的擁有者。
• 將基本集合串行化為資料庫所處理的某些數據行類型，例如，串行化至字串或從字串串列化。

第一個選項在許多情況下都有優點，我們將在本節結尾快速查看。 不過，它不是模型中數據的自然表示法，而且如果您真正擁有的是基本類型的集合，則第二個選項會更有效率。

從 Preview 4 開始，EF8 現在包含第二個選項的內建支援，使用 JSON 作為串行化格式。 因為新式關係資料庫包含查詢和操作 JSON 的內建機制，因此 JSON 數據行可以視需要有效地視為數據表，而不需要實際建立該數據表的額外負荷。 這些相同的機制可讓 JSON 傳入參數，然後在查詢中以類似方式使用數據表值參數，稍後再進行此動作。

基本集合屬性

EF Core 可以將任何 IEnumerable<T> 屬性，其中 T 是基本類型，對應至資料庫中的 JSON 數據行。 這是藉由具有 getter 和 setter 之公用屬性的慣例來完成。 例如，下列實體類型中的所有屬性都會依慣例對應至 JSON 數據行：

public class PrimitiveCollections
{
    public IEnumerable<int> Ints { get; set; }
    public ICollection<string> Strings { get; set; }
    public IList<DateOnly> Dates { get; set; }
    public uint[] UnsignedInts { get; set; }
    public List<bool> Booleans { get; set; }
    public List<Uri> Urls { get; set; }
}

根據預設，EF Core 會使用不受限制的 Unicode 字串數據行類型來保存 JSON，因為這可防止大型集合的數據遺失。 不過，在某些資料庫系統上，例如 SQL Server，指定字串的最大長度可以改善效能。 這與其他數據行組態一起，可以正常方式完成。 例如：

modelBuilder
    .Entity<PrimitiveCollections>()
    .Property(e => e.Booleans)
    .HasMaxLength(1024)
    .IsUnicode(false);

或者，使用對應屬性：

[MaxLength(2500)]
[Unicode(false)]
public uint[] UnsignedInts { get; set; }

默認數據行組態可用於使用 預先慣例模型組態的特定類型所有屬性。 例如：

protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder
        .Properties<List<DateOnly>>()
        .AreUnicode(false)
        .HaveMaxLength(4000);
}

具有基本集合的查詢

讓我們看看一些使用基本類型集合的查詢。 為此，我們需要具有兩個實體類型的簡單模型。 第一個 代表英國公共住宅或「酒吧」：

public class Pub
{
    public Pub(string name, string[] beers)
    {
        Name = name;
        Beers = beers;
    }

    public int Id { get; set; }
    public string Name { get; set; }
    public string[] Beers { get; set; }
    public List<DateOnly> DaysVisited { get; private set; } = new();
}

此 Pub 類型包含兩個基本集合：

• Beers 是一系列字串，代表酒吧提供的啤酒品牌。
• DaysVisited 是酒吧參觀日期的清單。

第二個實體類型代表在英國鄉村散步的狗：

public class DogWalk
{
    public DogWalk(string name)
    {
        Name = name;
    }

    public int Id { get; set; }
    public string Name { get; set; }
    public Terrain Terrain { get; set; }
    public List<DateOnly> DaysVisited { get; private set; } = new();
    public Pub ClosestPub { get; set; } = null!;
}

public enum Terrain
{
    Forest,
    River,
    Hills,
    Village,
    Park,
    Beach,
}

和 一樣 Pub， DogWalk 也包含參觀日期的集合，以及最接近酒吧的鏈接，因為，你知道，有時狗需要一個飛碟啤酒后長時間行走。

使用此模型，我們將執行的第一個查詢是一個簡單的 Contains 查詢，以尋找具有數個不同地形之一的所有步行：

var terrains = new[] { Terrain.River, Terrain.Beach, Terrain.Park };
var walksWithTerrain = await context.Walks
    .Where(e => terrains.Contains(e.Terrain))
    .Select(e => e.Name)
    .ToListAsync();

這已由目前的 EF Core 版本轉譯，方法是內嵌要尋找的值。 例如，使用 SQL Server 時：

SELECT [w].[Name]
FROM [Walks] AS [w]
WHERE [w].[Terrain] IN (1, 5, 4)

不過，此策略不適用於資料庫查詢快取;如需問題的討論，請參閱 .NET 部落格上的宣佈 EF8 Preview 4 。

針對EF Core 8，預設值現在是將地形清單當做包含 JSON 集合的單一參數來傳遞。 例如：

@__terrains_0='[1,5,4]'

查詢接著會在 OpenJson SQL Server 上使用：

SELECT [w].[Name]
FROM [Walks] AS [w]
WHERE EXISTS (
    SELECT 1
    FROM OpenJson(@__terrains_0) AS [t]
    WHERE CAST([t].[value] AS int) = [w].[Terrain])

或在 json_each SQLite 上：

SELECT "w"."Name"
FROM "Walks" AS "w"
WHERE EXISTS (
    SELECT 1
    FROM json_each(@__terrains_0) AS "t"
    WHERE "t"."value" = "w"."Terrain")

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    => optionsBuilder
        .UseSqlServer(
            @"Data Source=(LocalDb)\MSSQLLocalDB;Database=AllTogetherNow",
            sqlServerOptionsBuilder => sqlServerOptionsBuilder.UseCompatibilityLevel(120));

讓我們嘗試不同類型的 Contains 查詢。 在此情況下，我們會在數據行中尋找參數集合的值。 例如，任何股票海因肯的酒吧：

var beer = "Heineken";
var pubsWithHeineken = await context.Pubs
    .Where(e => e.Beers.Contains(beer))
    .Select(e => e.Name)
    .ToListAsync();

EF7 新功能的現有檔提供 JSON 對應、查詢和更新的詳細資訊。 本文件現在也適用於 SQLite。

SELECT [p].[Name]
FROM [Pubs] AS [p]
WHERE EXISTS (
    SELECT 1
    FROM OpenJson([p].[Beers]) AS [b]
    WHERE [b].[value] = @__beer_0)

OpenJson 現在用來從 JSON 數據行擷取值，讓每個值可以比對傳遞的參數。

我們可以在 參數OpenJson與 數據行上結合 的 用法OpenJson。 例如，若要尋找儲存任何一個各種延隔者的酒吧：

var beers = new[] { "Carling", "Heineken", "Stella Artois", "Carlsberg" };
var pubsWithLager = await context.Pubs
    .Where(e => beers.Any(b => e.Beers.Contains(b)))
    .Select(e => e.Name)
    .ToListAsync();

這會轉譯為 SQL Server 上的下列內容：

SELECT [p].[Name]
FROM [Pubs] AS [p]
WHERE EXISTS (
    SELECT 1
    FROM OpenJson(@__beers_0) AS [b]
    WHERE EXISTS (
        SELECT 1
        FROM OpenJson([p].[Beers]) AS [b0]
        WHERE [b0].[value] = [b].[value] OR ([b0].[value] IS NULL AND [b].[value] IS NULL)))

這裡的 @__beers_0 參數值是 ["Carling","Heineken","Stella Artois","Carlsberg"]。

讓我們看看使用包含日期集合之數據行的查詢。 例如，若要尋找今年造訪的酒吧：

var thisYear = DateTime.Now.Year;
var pubsVisitedThisYear = await context.Pubs
    .Where(e => e.DaysVisited.Any(v => v.Year == thisYear))
    .Select(e => e.Name)
    .ToListAsync();

這會轉譯為 SQL Server 上的下列內容：

SELECT [p].[Name]
FROM [Pubs] AS [p]
WHERE EXISTS (
    SELECT 1
    FROM OpenJson([p].[DaysVisited]) AS [d]
    WHERE DATEPART(year, CAST([d].[value] AS date)) = @__thisYear_0)

請注意，因為 EF 知道基本集合包含日期，因此查詢會在這裡使用日期特定函DATEPART式。 它似乎不像它，但這實際上真的很重要。 因為 EF 知道集合中的內容，所以可以產生適當的 SQL，以搭配參數、函式、其他數據行等使用具類型的值。

讓我們再次使用日期集合，這次會針對從集合擷取的類型和專案值適當排序。 例如，讓我們以第一次流覽的順序列出酒吧，以及每個酒吧流覽的第一個和最後一個日期：

var pubsVisitedInOrder = await context.Pubs
    .Select(e => new
    {
        e.Name,
        FirstVisited = e.DaysVisited.OrderBy(v => v).First(),
        LastVisited = e.DaysVisited.OrderByDescending(v => v).First(),
    })
    .OrderBy(p => p.FirstVisited)
    .ToListAsync();

這會轉譯為 SQL Server 上的下列內容：

SELECT [p].[Name], (
    SELECT TOP(1) CAST([d0].[value] AS date)
    FROM OpenJson([p].[DaysVisited]) AS [d0]
    ORDER BY CAST([d0].[value] AS date)) AS [FirstVisited], (
    SELECT TOP(1) CAST([d1].[value] AS date)
    FROM OpenJson([p].[DaysVisited]) AS [d1]
    ORDER BY CAST([d1].[value] AS date) DESC) AS [LastVisited]
FROM [Pubs] AS [p]
ORDER BY (
    SELECT TOP(1) CAST([d].[value] AS date)
    FROM OpenJson([p].[DaysVisited]) AS [d]
    ORDER BY CAST([d].[value] AS date))

最後，我們最後在帶狗散步時，最後參觀最接近的酒吧的頻率為何？ 讓我們來看看：

var walksWithADrink = await context.Walks.Select(
    w => new
    {
        WalkName = w.Name,
        PubName = w.ClosestPub.Name,
        Count = w.DaysVisited.Count(v => w.ClosestPub.DaysVisited.Contains(v)),
        TotalCount = w.DaysVisited.Count
    }).ToListAsync();

這會轉譯為 SQL Server 上的下列內容：

SELECT [w].[Name] AS [WalkName], [p].[Name] AS [PubName], (
    SELECT COUNT(*)
    FROM OpenJson([w].[DaysVisited]) AS [d]
    WHERE EXISTS (
        SELECT 1
        FROM OpenJson([p].[DaysVisited]) AS [d0]
        WHERE CAST([d0].[value] AS date) = CAST([d].[value] AS date) OR ([d0].[value] IS NULL AND [d].[value] IS NULL))) AS [Count], (
    SELECT COUNT(*)
    FROM OpenJson([w].[DaysVisited]) AS [d1]) AS [TotalCount]
FROM [Walks] AS [w]
INNER JOIN [Pubs] AS [p] ON [w].[ClosestPubId] = [p].[Id]

並顯示下列資料：

The Prince of Wales Feathers was visited 5 times in 8 "Ailsworth to Nene" walks.
The Prince of Wales Feathers was visited 6 times in 9 "Caster Hanglands" walks.
The Royal Oak was visited 6 times in 8 "Ferry Meadows" walks.
The White Swan was visited 7 times in 9 "Woodnewton" walks.
The Eltisley was visited 6 times in 8 "Eltisley" walks.
Farr Bay Inn was visited 7 times in 11 "Farr Beach" walks.
Farr Bay Inn was visited 7 times in 9 "Newlands" walks.

看起來啤酒和狗走是一個成功的組合！

JSON 檔中的基本集合

在上述所有範例中，基本集合的數據行包含 JSON。 不過，這與將擁有的實體類型對應 至包含EF7 中引進 JSON 文件的數據行不同。 但是，如果該 JSON 檔本身包含基本集合，該怎麼辦？ 嗯，上述所有查詢仍然以相同方式運作！ 例如，假設我們會將數據移至對應至 JSON 檔之自有類型的Visits天數：

public class Pub
{
    public Pub(string name)
    {
        Name = name;
    }

    public int Id { get; set; }
    public string Name { get; set; }
    public BeerData Beers { get; set; } = null!;
    public Visits Visits { get; set; } = null!;
}

public class Visits
{
    public string? LocationTag { get; set; }
    public List<DateOnly> DaysVisited { get; set; } = null!;
}

我們現在可以執行最後一個查詢的變化，這次，從 JSON 檔擷取數據，包括查詢到檔中包含的基本集合：

var walksWithADrink = await context.Walks.Select(
    w => new
    {
        WalkName = w.Name,
        PubName = w.ClosestPub.Name,
        WalkLocationTag = w.Visits.LocationTag,
        PubLocationTag = w.ClosestPub.Visits.LocationTag,
        Count = w.Visits.DaysVisited.Count(v => w.ClosestPub.Visits.DaysVisited.Contains(v)),
        TotalCount = w.Visits.DaysVisited.Count
    }).ToListAsync();

這會轉譯為 SQL Server 上的下列內容：

SELECT [w].[Name] AS [WalkName], [p].[Name] AS [PubName], JSON_VALUE([w].[Visits], '$.LocationTag') AS [WalkLocationTag], JSON_VALUE([p].[Visits], '$.LocationTag') AS [PubLocationTag], (
    SELECT COUNT(*)
    FROM OpenJson(JSON_VALUE([w].[Visits], '$.DaysVisited')) AS [d]
    WHERE EXISTS (
        SELECT 1
        FROM OpenJson(JSON_VALUE([p].[Visits], '$.DaysVisited')) AS [d0]
        WHERE CAST([d0].[value] AS date) = CAST([d].[value] AS date) OR ([d0].[value] IS NULL AND [d].[value] IS NULL))) AS [Count], (
    SELECT COUNT(*)
    FROM OpenJson(JSON_VALUE([w].[Visits], '$.DaysVisited')) AS [d1]) AS [TotalCount]
FROM [Walks] AS [w]
INNER JOIN [Pubs] AS [p] ON [w].[ClosestPubId] = [p].[Id]

使用 SQLite 時，與類似的查詢：

SELECT "w"."Name" AS "WalkName", "p"."Name" AS "PubName", "w"."Visits" ->> 'LocationTag' AS "WalkLocationTag", "p"."Visits" ->> 'LocationTag' AS "PubLocationTag", (
    SELECT COUNT(*)
    FROM json_each("w"."Visits" ->> 'DaysVisited') AS "d"
    WHERE EXISTS (
        SELECT 1
        FROM json_each("p"."Visits" ->> 'DaysVisited') AS "d0"
        WHERE "d0"."value" = "d"."value")) AS "Count", json_array_length("w"."Visits" ->> 'DaysVisited') AS "TotalCount"
FROM "Walks" AS "w"
INNER JOIN "Pubs" AS "p" ON "w"."ClosestPubId" = "p"."Id"

將基本集合對應至數據表

我們上面提到，基本集合的另一個選項是將它們對應至不同的數據表。 問題 #25163 會追蹤此專案的一等支援;如果您對此問題很重要，請務必投票處理此問題。 在實作之前，最好的方法是為基本類型建立包裝類型。 例如，讓我們建立的 型別 Beer：

[Owned]
public class Beer
{
    public Beer(string name)
    {
        Name = name;
    }

    public string Name { get; private set; }
}

請注意，此類型只會包裝基本值-- 它沒有主鍵或任何已定義的外鍵。 這個類型接著可以在 類別中使用 Pub ：

public class Pub
{
    public Pub(string name)
    {
        Name = name;
    }

    public int Id { get; set; }
    public string Name { get; set; }
    public List<Beer> Beers { get; set; } = new();
    public List<DateOnly> DaysVisited { get; private set; } = new();
}

EF 現在會建立 Beer 數據表，將主鍵和外鍵數據行合成回 Pubs 數據表。 例如，在 SQL Server 上：

CREATE TABLE [Beer] (
    [PubId] int NOT NULL,
    [Id] int NOT NULL IDENTITY,
    [Name] nvarchar(max) NOT NULL,
    CONSTRAINT [PK_Beer] PRIMARY KEY ([PubId], [Id]),
    CONSTRAINT [FK_Beer_Pubs_PubId] FOREIGN KEY ([PubId]) REFERENCES [Pubs] ([Id]) ON DELETE CASCADE

JSON 數據行對應的增強功能

EF8 包含 EF7 中引進的 JSON 數據行對應支援的改善。

將元素存取轉譯為 JSON 陣列

EF8 在執行查詢時，支援在 JSON 陣列中編製索引。 例如，下列查詢會檢查前兩個更新是否在指定的日期之前進行。

var cutoff = DateOnly.FromDateTime(DateTime.UtcNow - TimeSpan.FromDays(365));
var updatedPosts = await context.Posts
    .Where(
        p => p.Metadata!.Updates[0].UpdatedOn < cutoff
             && p.Metadata!.Updates[1].UpdatedOn < cutoff)
    .ToListAsync();

這會在使用 SQL Server 時轉譯成下列 SQL：

SELECT [p].[Id], [p].[Archived], [p].[AuthorId], [p].[BlogId], [p].[Content], [p].[Discriminator], [p].[PublishedOn], [p].[Title], [p].[PromoText], [p].[Metadata]
FROM [Posts] AS [p]
WHERE CAST(JSON_VALUE([p].[Metadata],'$.Updates[0].UpdatedOn') AS date) < @__cutoff_0
  AND CAST(JSON_VALUE([p].[Metadata],'$.Updates[1].UpdatedOn') AS date) < @__cutoff_0

將索引編製成 JSON 陣列也可以用來將陣列中的專案投影到最終結果。 例如，下列查詢會針對每個文章的第一次和第二次更新， UpdatedOn 將日期排除在外。

var postsAndRecentUpdatesNullable = await context.Posts
    .Select(p => new
    {
        p.Title,
        LatestUpdate = (DateOnly?)p.Metadata!.Updates[0].UpdatedOn,
        SecondLatestUpdate = (DateOnly?)p.Metadata.Updates[1].UpdatedOn
    })
    .ToListAsync();

這會在使用 SQL Server 時轉譯成下列 SQL：

SELECT [p].[Title],
       CAST(JSON_VALUE([p].[Metadata],'$.Updates[0].UpdatedOn') AS date) AS [LatestUpdate],
       CAST(JSON_VALUE([p].[Metadata],'$.Updates[1].UpdatedOn') AS date) AS [SecondLatestUpdate]
FROM [Posts] AS [p]

如上所述，如果陣列的 元素不存在， JSON_VALUE 則會傳回 null。 這會在查詢中處理，方法是將投影值轉換成可為 Null 的 DateOnly。 轉換值的替代方法是篩選查詢結果， JSON_VALUE 讓永遠不會傳回 Null。 例如：

var postsAndRecentUpdates = await context.Posts
    .Where(p => p.Metadata!.Updates[0].UpdatedOn != null
                && p.Metadata!.Updates[1].UpdatedOn != null)
    .Select(p => new
    {
        p.Title,
        LatestUpdate = p.Metadata!.Updates[0].UpdatedOn,
        SecondLatestUpdate = p.Metadata.Updates[1].UpdatedOn
    })
    .ToListAsync();

這會在使用 SQL Server 時轉譯成下列 SQL：

SELECT [p].[Title],
       CAST(JSON_VALUE([p].[Metadata],'$.Updates[0].UpdatedOn') AS date) AS [LatestUpdate],
       CAST(JSON_VALUE([p].[Metadata],'$.Updates[1].UpdatedOn') AS date) AS [SecondLatestUpdate]
FROM [Posts] AS [p]
      WHERE (CAST(JSON_VALUE([p].[Metadata],'$.Updates[0].UpdatedOn') AS date) IS NOT NULL)
        AND (CAST(JSON_VALUE([p].[Metadata],'$.Updates[1].UpdatedOn') AS date) IS NOT NULL)

將查詢轉譯成內嵌集合

EF8 支援針對 JSON 檔中內嵌的基本類型或非基本類型的集合進行查詢。 例如，下列查詢會傳回具有任何任意搜尋字詞清單的所有文章：

var searchTerms = new[] { "Search #2", "Search #3", "Search #5", "Search #8", "Search #13", "Search #21", "Search #34" };

var postsWithSearchTerms = await context.Posts
    .Where(post => post.Metadata!.TopSearches.Any(s => searchTerms.Contains(s.Term)))
    .ToListAsync();

這會在使用 SQL Server 時轉譯成下列 SQL：

SELECT [p].[Id], [p].[Archived], [p].[AuthorId], [p].[BlogId], [p].[Content], [p].[Discriminator], [p].[PublishedOn], [p].[Title], [p].[PromoText], [p].[Metadata]
FROM [Posts] AS [p]
WHERE EXISTS (
    SELECT 1
    FROM OPENJSON([p].[Metadata], '$.TopSearches') WITH (
        [Count] int '$.Count',
        [Term] nvarchar(max) '$.Term'
    ) AS [t]
    WHERE EXISTS (
        SELECT 1
        FROM OPENJSON(@__searchTerms_0) WITH ([value] nvarchar(max) '$') AS [s]
        WHERE [s].[value] = [t].[Term]))

SQLite 的 JSON 資料行

EF7 引進了在使用 Azure SQL/SQL Server 時對應至 JSON 數據行的支援。 EF8 會將這項支援延伸至 SQLite 資料庫。 至於 SQL Server 支援，這包括：

• 從 .NET 類型建置的匯總對應至儲存在 SQLite 數據行中的 JSON 檔
• 查詢 JSON 資料行，例如篩選和排序檔元素
• 查詢將 JSON 檔中的項目專案投射到結果中
• 更新和儲存 JSON 檔的變更

EF7 新功能的現有檔提供 JSON 對應、查詢和更新的詳細資訊。 本文件現在也適用於 SQLite。

查詢 JSON 數據行

在 SQLite 上查詢 JSON 數據行時，會使用 函 json_extract 式。 例如，上述檔中的「Chigley 中的作者」查詢：

var authorsInChigley = await context.Authors
    .Where(author => author.Contact.Address.City == "Chigley")
    .ToListAsync();

使用 SQLite 時會轉譯為下列 SQL：

SELECT "a"."Id", "a"."Name", "a"."Contact"
FROM "Authors" AS "a"
WHERE json_extract("a"."Contact", '$.Address.City') = 'Chigley'

更新 JSON 數據行

針對更新，EF 會在 SQLite 上使用 函 json_set 式。 例如，更新檔中的單一屬性時：

var arthur = await context.Authors.SingleAsync(author => author.Name.StartsWith("Arthur"));

arthur.Contact.Address.Country = "United Kingdom";

await context.SaveChangesAsync();

EF 會產生下列參數：

info: 3/10/2023 10:51:33.127 RelationalEventId.CommandExecuted[20101] (Microsoft.EntityFrameworkCore.Database.Command)
      Executed DbCommand (0ms) [Parameters=[@p0='["United Kingdom"]' (Nullable = false) (Size = 18), @p1='4'], CommandType='Text', CommandTimeout='30']

在 SQLite 上使用 函 json_set 式：

UPDATE "Authors" SET "Contact" = json_set("Contact", '$.Address.Country', json_extract(@p0, '$[0]'))
WHERE "Id" = @p1
RETURNING 1;

.NET 和 EF Core 中的 HierarchyId

Azure SQL 和 SQL Server 具有稱為 hierarchyid 的特殊數據類型，可用來儲存 階層式數據。 在此情況下，「階層式數據」基本上表示形成樹狀結構的數據，其中每個專案都可以有父系和/或子系。 這類資料的範例包括：

• 組織結構
• 檔案系統
• 專案中的一組工作
• 語言詞彙的分類表
• 網頁之間的連結圖形

資料庫接著可以使用其階層式結構，針對此數據執行查詢。 例如，查詢可以尋找給定專案的上階和相依專案，或尋找階層中特定深度的所有專案。

.NET 和 EF Core 中的支援

SQL Server hierarchyid 類型的正式支援最近才來到新式 .NET 平臺（也就是 “.NET Core” ）。 此支援的形式 為 Microsoft.SqlServer.Types NuGet 套件，其引進低階 SQL Server 特定類型。 在這裡情況下，低階類型稱為 SqlHierarchyId。

在下一個層級中，引進了新的 Microsoft.EntityFrameworkCore.SqlServer.Abstractions 套件，其中包含用於實體類型的高階 HierarchyId 類型。

HierarchyId針對EF Core功能使用 ，例如查詢和更新需要 Microsoft.EntityFrameworkCore.SqlServer.HierarchyId 套件。 此套件引進 Microsoft.EntityFrameworkCore.SqlServer.Abstractions 和 Microsoft.SqlServer.Types 作為可轉移的相依性，因此通常是唯一所需的套件。 安裝套件之後，藉由呼叫 UseHierarchyId 作為應用程式呼叫 UseSqlServer的一部分，啟用的用法HierarchyId。 例如：

options.UseSqlServer(
    connectionString,
    x => x.UseHierarchyId());

模型化階層

此 HierarchyId 類型可用於實體類型的屬性。 例如，假設我們想要模型化一些虛構 半身子的父系家族樹。 在的 Halfling實體類型中， HierarchyId 屬性可用來找出家族樹狀結構中的每個半角。

public class Halfling
{
    public Halfling(HierarchyId pathFromPatriarch, string name, int? yearOfBirth = null)
    {
        PathFromPatriarch = pathFromPatriarch;
        Name = name;
        YearOfBirth = yearOfBirth;
    }

    public int Id { get; private set; }
    public HierarchyId PathFromPatriarch { get; set; }
    public string Name { get; set; }
    public int? YearOfBirth { get; set; }
}

在此情況下，家族樹是以家族的父權階層為根。 每半項都可以使用其 PathFromPatriarch 屬性從樹狀結構中的父階層追蹤。 SQL Server 會針對這些路徑使用精簡的二進位格式，但在使用程式代碼時，通常會剖析人類可讀取的字串表示法。 在此表示法中，每個層級的位置會以 / 字元分隔。 例如，請考慮下圖中的家族樹狀結構：

在此樹狀結構中：

• Balbo 位於樹狀結構的根目錄，以 /表示。
• Balbo 有五個子系，由 /1/、 /2/、 /3/、 /4/和 /5/表示。
• 巴爾博的第一個孩子蒙戈也有五個孩子，由 /1/1/、 /1/2/、 /1/3/、 /1/4/和 /1/5/代表。 請注意， HierarchyId 巴爾博 （/1/） 的 是他所有孩子的前置詞。
• 同樣地，巴爾博的第三個孩子龐托有兩個孩子，由 /3/1/ 和 /3/2/代表。 同樣地，這些子系前面會加上 HierarchyId Ponto 的 ，其表示為 /3/。
• 樹下等等...

下列程式代碼會使用 EF Core 將此家族樹插入資料庫中：

await AddRangeAsync(
    new Halfling(HierarchyId.Parse("/"), "Balbo", 1167),
    new Halfling(HierarchyId.Parse("/1/"), "Mungo", 1207),
    new Halfling(HierarchyId.Parse("/2/"), "Pansy", 1212),
    new Halfling(HierarchyId.Parse("/3/"), "Ponto", 1216),
    new Halfling(HierarchyId.Parse("/4/"), "Largo", 1220),
    new Halfling(HierarchyId.Parse("/5/"), "Lily", 1222),
    new Halfling(HierarchyId.Parse("/1/1/"), "Bungo", 1246),
    new Halfling(HierarchyId.Parse("/1/2/"), "Belba", 1256),
    new Halfling(HierarchyId.Parse("/1/3/"), "Longo", 1260),
    new Halfling(HierarchyId.Parse("/1/4/"), "Linda", 1262),
    new Halfling(HierarchyId.Parse("/1/5/"), "Bingo", 1264),
    new Halfling(HierarchyId.Parse("/3/1/"), "Rosa", 1256),
    new Halfling(HierarchyId.Parse("/3/2/"), "Polo"),
    new Halfling(HierarchyId.Parse("/4/1/"), "Fosco", 1264),
    new Halfling(HierarchyId.Parse("/1/1/1/"), "Bilbo", 1290),
    new Halfling(HierarchyId.Parse("/1/3/1/"), "Otho", 1310),
    new Halfling(HierarchyId.Parse("/1/5/1/"), "Falco", 1303),
    new Halfling(HierarchyId.Parse("/3/2/1/"), "Posco", 1302),
    new Halfling(HierarchyId.Parse("/3/2/2/"), "Prisca", 1306),
    new Halfling(HierarchyId.Parse("/4/1/1/"), "Dora", 1302),
    new Halfling(HierarchyId.Parse("/4/1/2/"), "Drogo", 1308),
    new Halfling(HierarchyId.Parse("/4/1/3/"), "Dudo", 1311),
    new Halfling(HierarchyId.Parse("/1/3/1/1/"), "Lotho", 1310),
    new Halfling(HierarchyId.Parse("/1/5/1/1/"), "Poppy", 1344),
    new Halfling(HierarchyId.Parse("/3/2/1/1/"), "Ponto", 1346),
    new Halfling(HierarchyId.Parse("/3/2/1/2/"), "Porto", 1348),
    new Halfling(HierarchyId.Parse("/3/2/1/3/"), "Peony", 1350),
    new Halfling(HierarchyId.Parse("/4/1/2/1/"), "Frodo", 1368),
    new Halfling(HierarchyId.Parse("/4/1/3/1/"), "Daisy", 1350),
    new Halfling(HierarchyId.Parse("/3/2/1/1/1/"), "Angelica", 1381));

await SaveChangesAsync();

查詢階層

HierarchyId 會公開數個可用於 LINQ 查詢的方法。

此外，可以使用運算子==、!=、<、 <=> 和 >= 。

以下是在 LINQ 查詢中使用這些方法的範例。

取得樹狀結構中指定層級的實體

下列查詢會使用 GetLevel 傳回家族樹中指定層級的所有半項：

var generation = await context.Halflings.Where(halfling => halfling.PathFromPatriarch.GetLevel() == level).ToListAsync();

這會轉譯為下列 SQL：

SELECT [h].[Id], [h].[Name], [h].[PathFromPatriarch], [h].[YearOfBirth]
FROM [Halflings] AS [h]
WHERE [h].[PathFromPatriarch].GetLevel() = @__level_0

在迴圈中執行此作業，我們可以取得每一代的半角：

Generation 0: Balbo
Generation 1: Mungo, Pansy, Ponto, Largo, Lily
Generation 2: Bungo, Belba, Longo, Linda, Bingo, Rosa, Polo, Fosco
Generation 3: Bilbo, Otho, Falco, Posco, Prisca, Dora, Drogo, Dudo
Generation 4: Lotho, Poppy, Ponto, Porto, Peony, Frodo, Daisy
Generation 5: Angelica

取得實體的直接上階

下列查詢會使用 GetAncestor 來尋找半身分的直接上階，因為有一半的名稱：

async Task<Halfling?> FindDirectAncestor(string name)
    => await context.Halflings
        .SingleOrDefaultAsync(
            ancestor => ancestor.PathFromPatriarch == context.Halflings
                .Single(descendent => descendent.Name == name).PathFromPatriarch
                .GetAncestor(1));

這會轉譯為下列 SQL：

SELECT TOP(2) [h].[Id], [h].[Name], [h].[PathFromPatriarch], [h].[YearOfBirth]
FROM [Halflings] AS [h]
WHERE [h].[PathFromPatriarch] = (
    SELECT TOP(1) [h0].[PathFromPatriarch]
    FROM [Halflings] AS [h0]
    WHERE [h0].[Name] = @__name_0).GetAncestor(1)

執行此查詢以取得半角 「Bilbo」 會傳回 「Bungo」。

取得實體的直接子代

下列查詢也會使用 GetAncestor，但這次會尋找半元的直接子代，因為有半分號的名稱：

IQueryable<Halfling> FindDirectDescendents(string name)
    => context.Halflings.Where(
        descendent => descendent.PathFromPatriarch.GetAncestor(1) == context.Halflings
            .Single(ancestor => ancestor.Name == name).PathFromPatriarch);

這會轉譯為下列 SQL：

SELECT [h].[Id], [h].[Name], [h].[PathFromPatriarch], [h].[YearOfBirth]
FROM [Halflings] AS [h]
WHERE [h].[PathFromPatriarch].GetAncestor(1) = (
    SELECT TOP(1) [h0].[PathFromPatriarch]
    FROM [Halflings] AS [h0]
    WHERE [h0].[Name] = @__name_0)

執行此查詢以取得半角 「Mungo」 會傳回 「Bungo」、“Belba”、“Longo” 和 “Linda”。

取得實體的所有上階

GetAncestor 對於搜尋單一層級或向下搜尋，或確實是指定的層級數目很有用。 另一方面， IsDescendantOf 對於尋找所有上階或相依專案很有用。 例如，下列查詢會使用 IsDescendantOf 來尋找半階的所有上階，因為該半元的名稱如下：

IQueryable<Halfling> FindAllAncestors(string name)
    => context.Halflings.Where(
            ancestor => context.Halflings
                .Single(
                    descendent =>
                        descendent.Name == name
                        && ancestor.Id != descendent.Id)
                .PathFromPatriarch.IsDescendantOf(ancestor.PathFromPatriarch))
        .OrderByDescending(ancestor => ancestor.PathFromPatriarch.GetLevel());

這會轉譯為下列 SQL：

SELECT [h].[Id], [h].[Name], [h].[PathFromPatriarch], [h].[YearOfBirth]
FROM [Halflings] AS [h]
WHERE (
    SELECT TOP(1) [h0].[PathFromPatriarch]
    FROM [Halflings] AS [h0]
    WHERE [h0].[Name] = @__name_0 AND [h].[Id] <> [h0].[Id]).IsDescendantOf([h].[PathFromPatriarch]) = CAST(1 AS bit)
ORDER BY [h].[PathFromPatriarch].GetLevel() DESC

執行此查詢來尋找半角 「Bilbo」 會傳回 「Bungo」、“Mungo” 和 “Balbo”。

取得實體的所有子代

下列查詢也會使用 ，但這次會使用 IsDescendantOf半元的所有子代，因為有半個子系的名稱：

IQueryable<Halfling> FindAllDescendents(string name)
    => context.Halflings.Where(
            descendent => descendent.PathFromPatriarch.IsDescendantOf(
                context.Halflings
                    .Single(
                        ancestor =>
                            ancestor.Name == name
                            && descendent.Id != ancestor.Id)
                    .PathFromPatriarch))
        .OrderBy(descendent => descendent.PathFromPatriarch.GetLevel());

這會轉譯為下列 SQL：

SELECT [h].[Id], [h].[Name], [h].[PathFromPatriarch], [h].[YearOfBirth]
FROM [Halflings] AS [h]
WHERE [h].[PathFromPatriarch].IsDescendantOf((
    SELECT TOP(1) [h0].[PathFromPatriarch]
    FROM [Halflings] AS [h0]
    WHERE [h0].[Name] = @__name_0 AND [h].[Id] <> [h0].[Id])) = CAST(1 AS bit)
ORDER BY [h].[PathFromPatriarch].GetLevel()

執行此查詢時，Mungo 的半角 「Mungo」 會傳回 「Bungo」、“Belba”、“Longo”、“Linda”、“Bingo”、“Bilbo”、“Otho”、“Falco”、“Lotho” 和 “Popy”。

尋找常見的上階

關於這個特定家族樹的最常見問題之一是，「誰是弗羅多和比爾博的共同祖先？我們可用來 IsDescendantOf 撰寫這類查詢：

async Task<Halfling?> FindCommonAncestor(Halfling first, Halfling second)
    => await context.Halflings
        .Where(
            ancestor => first.PathFromPatriarch.IsDescendantOf(ancestor.PathFromPatriarch)
                        && second.PathFromPatriarch.IsDescendantOf(ancestor.PathFromPatriarch))
        .OrderByDescending(ancestor => ancestor.PathFromPatriarch.GetLevel())
        .FirstOrDefaultAsync();

這會轉譯為下列 SQL：

SELECT TOP(1) [h].[Id], [h].[Name], [h].[PathFromPatriarch], [h].[YearOfBirth]
FROM [Halflings] AS [h]
WHERE @__first_PathFromPatriarch_0.IsDescendantOf([h].[PathFromPatriarch]) = CAST(1 AS bit)
  AND @__second_PathFromPatriarch_1.IsDescendantOf([h].[PathFromPatriarch]) = CAST(1 AS bit)
ORDER BY [h].[PathFromPatriarch].GetLevel() DESC

使用 「Bilbo」 和 「Frodo」 執行此查詢會告訴我們，其共同祖先是 「Balbo」。

更新階層

一般 變更追蹤 和 SaveChanges 機制可用來更新數據 hierarchyid 行。

重新上層子階層

例如，我相信我們都記得SR 1752（也就是“朗哥門”）的醜聞，當DNA測試顯示朗戈不是蒙戈的兒子，但實際上龐托的兒子！ 這起醜聞的一個后因是家庭樹需要重新寫。 特別是，朗戈和他的所有後裔都需要從蒙戈重新養育到龐托。 GetReparentedValue 可以用來執行這項操作。 例如，會查詢第一個 「Longo」 及其所有子代：

var longoAndDescendents = await context.Halflings.Where(
        descendent => descendent.PathFromPatriarch.IsDescendantOf(
            context.Halflings.Single(ancestor => ancestor.Name == "Longo").PathFromPatriarch))
    .ToListAsync();

接著 GetReparentedValue 會用來更新 HierarchyId Longo 和每個子系的 ，後面接著呼叫 SaveChangesAsync：

foreach (var descendent in longoAndDescendents)
{
    descendent.PathFromPatriarch
        = descendent.PathFromPatriarch.GetReparentedValue(
            mungo.PathFromPatriarch, ponto.PathFromPatriarch)!;
}

await context.SaveChangesAsync();

這會導致下列資料庫更新：

SET NOCOUNT ON;
UPDATE [Halflings] SET [PathFromPatriarch] = @p0
OUTPUT 1
WHERE [Id] = @p1;
UPDATE [Halflings] SET [PathFromPatriarch] = @p2
OUTPUT 1
WHERE [Id] = @p3;
UPDATE [Halflings] SET [PathFromPatriarch] = @p4
OUTPUT 1
WHERE [Id] = @p5;

使用這些參數：

 @p1='9',
 @p0='0x7BC0' (Nullable = false) (Size = 2) (DbType = Object),
 @p3='16',
 @p2='0x7BD6' (Nullable = false) (Size = 2) (DbType = Object),
 @p5='23',
 @p4='0x7BD6B0' (Nullable = false) (Size = 3) (DbType = Object)

更新之後，查詢 「Mungo」 的子系會傳回 「Bungo」 “ Belba”、“Linda”、“Bingo”、“Bilbo”、“Falco”和 “Popy”，同時查詢 “Ponto” 的子系會傳回 “Longo”、“Rosa”、“Polo”、“Otho”、“Posco”、“Prisca”、“Lotho”、“Ponto”、“波爾圖”、“牡丹”和 “Angelica”。

未對應的原始 SQL 查詢

EF7 引進傳 回純量類型的原始 SQL 查詢。 這在 EF8 中增強，可包含傳回任何可對應 CLR 類型的未經處理的 SQL 查詢，而不會在 EF 模型中包含該類型。

使用未對應的型別的查詢會使用 SqlQuery 或 SqlQueryRaw來執行。 前者會使用字串插補來參數化查詢，這有助於確保所有非常數值都參數化。 例如，請考慮下列資料庫數據表：

CREATE TABLE [Posts] (
    [Id] int NOT NULL IDENTITY,
    [Title] nvarchar(max) NOT NULL,
    [Content] nvarchar(max) NOT NULL,
    [PublishedOn] date NOT NULL,
    [BlogId] int NOT NULL,
);

SqlQuery 可用來查詢此數據表，並傳回類型的實例 BlogPost ，其屬性對應至數據表中的數據行：

例如：

public class BlogPost
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }
    public DateOnly PublishedOn { get; set; }
    public int BlogId { get; set; }
}

例如：

var start = new DateOnly(2022, 1, 1);
var end = new DateOnly(2023, 1, 1);
var postsIn2022 =
    await context.Database
        .SqlQuery<BlogPost>($"SELECT * FROM Posts as p WHERE p.PublishedOn >= {start} AND p.PublishedOn < {end}")
        .ToListAsync();

此查詢會參數化並執行為：

SELECT * FROM Posts as p WHERE p.PublishedOn >= @p0 AND p.PublishedOn < @p1

用於查詢結果的類型可以包含EF Core 支援的常見對應建構，例如參數化建構函式和對應屬性。 例如：

public class BlogPost
{
    public BlogPost(string blogTitle, string content, DateOnly publishedOn)
    {
        BlogTitle = blogTitle;
        Content = content;
        PublishedOn = publishedOn;
    }

    public int Id { get; private set; }

    [Column("Title")]
    public string BlogTitle { get; set; }

    public string Content { get; set; }
    public DateOnly PublishedOn { get; set; }
    public int BlogId { get; set; }
}

使用的類型必須具有結果集中每個值的屬性，但不需要比對資料庫中的任何數據表。 例如，下列類型只代表每個文章的資訊子集，並包含來自數據表的 Blogs 部落格名稱：

public class PostSummary
{
    public string BlogName { get; set; } = null!;
    public string PostTitle { get; set; } = null!;
    public DateOnly? PublishedOn { get; set; }
}

而且可以使用與之前相同的方式來查詢 SqlQuery ：

var cutoffDate = new DateOnly(2022, 1, 1);
var summaries =
    await context.Database.SqlQuery<PostSummary>(
            @$"SELECT b.Name AS BlogName, p.Title AS PostTitle, p.PublishedOn
               FROM Posts AS p
               INNER JOIN Blogs AS b ON p.BlogId = b.Id
               WHERE p.PublishedOn >= {cutoffDate}")
        .ToListAsync();

的其中一個不錯功能 SqlQuery 是，它會傳回 IQueryable 可使用 LINQ 撰寫的 。 例如，可以將 'Where' 子句新增至上述查詢：

var summariesIn2022 =
    await context.Database.SqlQuery<PostSummary>(
            @$"SELECT b.Name AS BlogName, p.Title AS PostTitle, p.PublishedOn
               FROM Posts AS p
               INNER JOIN Blogs AS b ON p.BlogId = b.Id")
        .Where(p => p.PublishedOn >= cutoffDate && p.PublishedOn < end)
        .ToListAsync();

這會以下列方式執行：

SELECT [n].[BlogName], [n].[PostTitle], [n].[PublishedOn]
FROM (
         SELECT b.Name AS BlogName, p.Title AS PostTitle, p.PublishedOn
         FROM Posts AS p
                  INNER JOIN Blogs AS b ON p.BlogId = b.Id
     ) AS [n]
WHERE [n].[PublishedOn] >= @__cutoffDate_1 AND [n].[PublishedOn] < @__end_2

此時值得記住，上述所有專案都可以完全在LINQ中完成，而不需要撰寫任何SQL。 這包括傳回未對應的型別實例，例如 PostSummary。 例如，上述查詢可以用 LINQ 撰寫為：

var summaries =
    await context.Posts.Select(
            p => new PostSummary
            {
                BlogName = p.Blog.Name,
                PostTitle = p.Title,
                PublishedOn = p.PublishedOn,
            })
        .Where(p => p.PublishedOn >= start && p.PublishedOn < end)
        .ToListAsync();

這會轉譯成更簡潔的 SQL：

SELECT [b].[Name] AS [BlogName], [p].[Title] AS [PostTitle], [p].[PublishedOn]
FROM [Posts] AS [p]
INNER JOIN [Blogs] AS [b] ON [p].[BlogId] = [b].[Id]
WHERE [p].[PublishedOn] >= @__start_0 AND [p].[PublishedOn] < @__end_1

到目前為止，所有查詢都已直接針對數據表執行。 SqlQuery 也可以用來傳回檢視的結果，而不需要對應 EF 模型中的檢視類型。 例如：

var summariesFromView =
    await context.Database.SqlQuery<PostSummary>(
            @$"SELECT * FROM PostAndBlogSummariesView")
        .Where(p => p.PublishedOn >= cutoffDate && p.PublishedOn < end)
        .ToListAsync();

同樣地， SqlQuery 可用於函式的結果：

var summariesFromFunc =
    await context.Database.SqlQuery<PostSummary>(
            @$"SELECT * FROM GetPostsPublishedAfter({cutoffDate})")
        .Where(p => p.PublishedOn < end)
        .ToListAsync();

當傳回 IQueryable 的 是檢視或函式的結果時，可以撰寫，就如同數據表查詢的結果一樣。 預存程式也可以使用 來執行 SqlQuery，但大部分的資料庫都不支援透過它們撰寫。 例如：

var summariesFromStoredProc =
    await context.Database.SqlQuery<PostSummary>(
            @$"exec GetRecentPostSummariesProc")
        .ToListAsync();

延遲載入的增強功能

無追蹤查詢的延遲載入

EF8 新增對未追蹤DbContext之實體上瀏覽延遲載入的支援。 這表示不追蹤查詢可以接著在無追蹤查詢所傳回的實體上延遲載入導覽。

例如，請考慮不追蹤部落格的查詢：

var blogs = await context.Blogs.AsNoTracking().ToListAsync();

如果 Blog.Posts 已設定延遲載入，例如，使用延遲載入 Proxy，則存取 Posts 會導致它從資料庫載入：

Console.WriteLine();
Console.Write("Choose a blog: ");
if (int.TryParse(ReadLine(), out var blogId))
{
    Console.WriteLine("Posts:");
    foreach (var post in blogs[blogId - 1].Posts)
    {
        Console.WriteLine($"  {post.Title}");
    }
}

EF8 也會報告是否針對內容未追蹤的實體載入指定的導覽。 例如：

foreach (var blog in blogs)
{
    if (context.Entry(blog).Collection(e => e.Posts).IsLoaded)
    {
        Console.WriteLine($" Posts for blog '{blog.Name}' are loaded.");
    }
}

以這種方式使用延遲載入時，有幾個重要考慮：

• 延遲載入只會成功，直到 DbContext 用來查詢實體的 處置為止。
• 以這種方式查詢的實體會維護其 DbContext參考，即使它們並未受到追蹤也一樣。 如果實體實例的存留期很長，就應該小心避免記憶體流失。
• 藉由設定實體的狀態來 EntityState.Detached 明確中斷鏈接實體，而延遲載入的參考 DbContext 將無法再運作。
• 請記住，所有延遲載入都會使用同步 I/O，因為無法以異步方式存取屬性。

從未追蹤的實體延遲載入適用於 延遲載入 Proxy 和 沒有 Proxy 的延遲載入。

從未追蹤的實體明確載入

EF8 支援在未追蹤的實體上載入導覽，即使未設定延遲載入的實體或流覽也一併載入。 不同於延遲載入， 此明確載入 可以異步完成。 例如：

await context.Entry(blog).Collection(e => e.Posts).LoadAsync();

退出退出特定導覽的延遲載入

EF8 允許設定特定導覽，使其不延遲載入，即使其他所有專案都設定為這麼做也一樣。 例如，若要將 Post.Author 瀏覽設定為不延遲載入，請執行下列動作：

modelBuilder
    .Entity<Post>()
    .Navigation(p => p.Author)
    .EnableLazyLoading(false);

停用延遲載入，這適用於 延遲載入 Proxy 和 沒有 Proxy 的延遲載入。

延遲載入 Proxy 的運作方式是覆寫虛擬導覽屬性。 在傳統EF6 應用程式中，常見的 Bug 來源會忘記讓流覽虛擬，因為流覽會以無訊息方式不延遲載入。 因此，當導覽不是虛擬時，EF Core Proxy 預設會擲回。

這可以在EF8 中變更為選擇加入傳統 EF6 行為，如此一來，只要讓流覽非虛擬，即可將瀏覽設為不延遲載入。 這個選擇加入設定為呼叫 UseLazyLoadingProxies的一部分。 例如：

optionsBuilder.UseLazyLoadingProxies(b => b.IgnoreNonVirtualNavigations());

存取追蹤的實體

依主要、替代或外鍵查閱追蹤的實體

在內部，EF 會維護數據結構，以便依主要、替代或外鍵尋找追蹤的實體。 當追蹤新實體或關聯性變更時，這些數據結構可用來有效修正相關實體。

EF8 包含新的公用 API，讓應用程式現在可以使用這些數據結構有效率地查閱追蹤的實體。 這些 API 是透過 LocalView<TEntity> 實體類型的 存取。 例如，若要依其主鍵查閱追蹤實體：

var blogEntry = context.Blogs.Local.FindEntry(2)!;

方法 FindEntry 會傳 EntityEntry<TEntity> 回所追蹤實體的 ，如果 null 未追蹤具有指定索引鍵的實體，則傳回 。 和上 LocalView的所有方法一樣，即使找不到實體，也不會查詢資料庫。 傳回的專案包含實體本身，以及追蹤資訊。 例如：

Console.WriteLine($"Blog '{blogEntry.Entity.Name}' with key {blogEntry.Entity.Id} is tracked in the '{blogEntry.State}' state.");

除了主鍵以外，查詢實體時，需要指定屬性名稱。 例如，若要依替代索引鍵查閱：

var siteEntry = context.Websites.Local.FindEntry(nameof(Website.Uri), new Uri("https://www.bricelam.net/"))!;

或者，若要透過唯一的外鍵查閱：

var blogAtSiteEntry = context.Blogs.Local.FindEntry(nameof(Blog.SiteUri), new Uri("https://www.bricelam.net/"))!;

到目前為止，查閱一律會傳回單一專案或 null。 不過，某些查閱可能會傳回一個以上的專案，例如透過非唯一外鍵查閱時。 方法 GetEntries 應該用於這些查閱。 例如：

var postEntries = context.Posts.Local.GetEntries(nameof(Post.BlogId), 2);

在這些情況下，用於查閱的值是主鍵、替代索引鍵或外鍵值。 EF 會針對這些查閱使用其內部數據結構。 不過，依值查閱也可用於任何屬性的值或屬性的組合。 例如，若要尋找所有封存文章：

var archivedPostEntries = context.Posts.Local.GetEntries(nameof(Post.Archived), true);

此查閱需要掃描所有追蹤 Post 的實例，因此會比索引鍵查閱效率低。 不過，使用的查詢通常仍然比天真查詢 ChangeTracker.Entries<TEntity>()更快。

最後，您也可以對複合索引鍵、多個屬性的其他組合，或在編譯時期不知道屬性類型時執行查閱。 例如：

var postTagEntry = context.Set<PostTag>().Local.FindEntryUntyped(new object[] { 4, "TagEF" });

模型建置

歧視性數據行的長度上限

在 EF8 中，用於 TPH 繼承對應的 字串歧視性數據行現在已設定長度上限。 此長度會計算為涵蓋所有已定義之歧視性值的最小 Fibonacci 數位。 例如，請考慮下列階層：

public abstract class Document
{
    public int Id { get; set; }
    public string Title { get; set; }
}

public abstract class Book : Document
{
    public string? Isbn { get; set; }
}

public class PaperbackEdition : Book
{
}

public class HardbackEdition : Book
{
}

public class Magazine : Document
{
    public int IssueNumber { get; set; }
}

使用歧視性值的類別名稱慣例，這裡的可能值為 “PaperbackEdition”、“HardbackEdition” 和 “Magazine”，因此將歧視性數據行設定為長度上限為 21。 例如，使用 SQL Server 時：

CREATE TABLE [Documents] (
    [Id] int NOT NULL IDENTITY,
    [Title] nvarchar(max) NOT NULL,
    [Discriminator] nvarchar(21) NOT NULL,
    [Isbn] nvarchar(max) NULL,
    [IssueNumber] int NULL,
    CONSTRAINT [PK_Documents] PRIMARY KEY ([Id]),

SQL Server 上支援的 DateOnly/TimeOnly

DateOnly和 TimeOnly 類型是在 .NET 6 中引進的，自推出以來，已支援數個資料庫提供者（例如 SQLite、MySQL 和 PostgreSQL）。 針對 SQL Server，以 .NET 6 為目標的 Microsoft.Data.SqlClient 套件最新版本已允許 ErikEJ 在 ADO.NET 層級新增這些類型的支援。 這反過來又為 EF8 的支援 DateOnly 鋪平了實體類型中的 屬性 TimeOnly 。

例如，請考慮下列英國學校的 EF 模型：

public class School
{
    public int Id { get; set; }
    public string Name { get; set; } = null!;
    public DateOnly Founded { get; set; }
    public List<Term> Terms { get; } = new();
    public List<OpeningHours> OpeningHours { get; } = new();
}

public class Term
{
    public int Id { get; set; }
    public string Name { get; set; } = null!;
    public DateOnly FirstDay { get; set; }
    public DateOnly LastDay { get; set; }
    public School School { get; set; } = null!;
}

[Owned]
public class OpeningHours
{
    public OpeningHours(DayOfWeek dayOfWeek, TimeOnly? opensAt, TimeOnly? closesAt)
    {
        DayOfWeek = dayOfWeek;
        OpensAt = opensAt;
        ClosesAt = closesAt;
    }

    public DayOfWeek DayOfWeek { get; private set; }
    public TimeOnly? OpensAt { get; set; }
    public TimeOnly? ClosesAt { get; set; }
}

這些實體類型會在使用 SQL Server 時對應至下表。 請注意， DateOnly 屬性會對應至 date 數據行，而 TimeOnly 屬性會對應至數據行 time 。

CREATE TABLE [Schools] (
    [Id] int NOT NULL IDENTITY,
    [Name] nvarchar(max) NOT NULL,
    [Founded] date NOT NULL,
    CONSTRAINT [PK_Schools] PRIMARY KEY ([Id]));

CREATE TABLE [OpeningHours] (
    [SchoolId] int NOT NULL,
    [Id] int NOT NULL IDENTITY,
    [DayOfWeek] int NOT NULL,
    [OpensAt] time NULL,
    [ClosesAt] time NULL,
    CONSTRAINT [PK_OpeningHours] PRIMARY KEY ([SchoolId], [Id]),
    CONSTRAINT [FK_OpeningHours_Schools_SchoolId] FOREIGN KEY ([SchoolId]) REFERENCES [Schools] ([Id]) ON DELETE CASCADE);

CREATE TABLE [Term] (
    [Id] int NOT NULL IDENTITY,
    [Name] nvarchar(max) NOT NULL,
    [FirstDay] date NOT NULL,
    [LastDay] date NOT NULL,
    [SchoolId] int NOT NULL,
    CONSTRAINT [PK_Term] PRIMARY KEY ([Id]),
    CONSTRAINT [FK_Term_Schools_SchoolId] FOREIGN KEY ([SchoolId]) REFERENCES [Schools] ([Id]) ON DELETE CASCADE);

使用 DateOnly 和 TimeOnly 的查詢會以預期的方式運作。 例如，下列 LINQ 查詢會尋找目前開啟的學校：

openSchools = await context.Schools
    .Where(
        s => s.Terms.Any(
                 t => t.FirstDay <= today
                      && t.LastDay >= today)
             && s.OpeningHours.Any(
                 o => o.DayOfWeek == dayOfWeek
                      && o.OpensAt < time && o.ClosesAt >= time))
    .ToListAsync();

此查詢會轉譯為下列 SQL，如 所示 ToQueryString：

DECLARE @__today_0 date = '2023-02-07';
DECLARE @__dayOfWeek_1 int = 2;
DECLARE @__time_2 time = '19:53:40.4798052';

SELECT [s].[Id], [s].[Founded], [s].[Name], [o0].[SchoolId], [o0].[Id], [o0].[ClosesAt], [o0].[DayOfWeek], [o0].[OpensAt]
FROM [Schools] AS [s]
LEFT JOIN [OpeningHours] AS [o0] ON [s].[Id] = [o0].[SchoolId]
WHERE EXISTS (
    SELECT 1
    FROM [Term] AS [t]
    WHERE [s].[Id] = [t].[SchoolId] AND [t].[FirstDay] <= @__today_0 AND [t].[LastDay] >= @__today_0) AND EXISTS (
    SELECT 1
    FROM [OpeningHours] AS [o]
    WHERE [s].[Id] = [o].[SchoolId] AND [o].[DayOfWeek] = @__dayOfWeek_1 AND [o].[OpensAt] < @__time_2 AND [o].[ClosesAt] >= @__time_2)
ORDER BY [s].[Id], [o0].[SchoolId]

DateOnly 和 TimeOnly 也可用於 JSON 數據行。 例如， OpeningHours 可以儲存為 JSON 檔，進而產生如下所示的數據：

[
  { “DayOfWeek”： “Sunday”， “ClosesAt”： null， “OpensAt”： null }，
  { “DayOfWeek”： “Monday”， “ClosesAt”： “15：35：00”， “OpensAt”： “08：45：00” }，
  { “DayOfWeek”： “Tuesday”， “ClosesAt”： “15：35：00”， “OpensAt”： “08：45：00” }，
  { “DayOfWeek”： “Wednesday”， “ClosesAt”： “15：35：00”， “OpensAt”： “08：45：00” }，
  { “DayOfWeek”： “Thursday”， “ClosesAt”： “15：35：00”， “OpensAt”： “08：45：00” }，
  { “DayOfWeek”： “Friday”， “ClosesAt”： “12：50：00”， “OpensAt”： “08：45：00” }，
  { “DayOfWeek”： “Saturday”， “ClosesAt”： null， “OpensAt”： null }
]

結合EF8的兩個功能，我們現在可以藉由編製索引至 JSON 集合來查詢上班時間。 例如：

openSchools = await context.Schools
    .Where(
        s => s.Terms.Any(
                 t => t.FirstDay <= today
                      && t.LastDay >= today)
             && s.OpeningHours[(int)dayOfWeek].OpensAt < time
             && s.OpeningHours[(int)dayOfWeek].ClosesAt >= time)
    .ToListAsync();

此查詢會轉譯為下列 SQL，如 所示 ToQueryString：

DECLARE @__today_0 date = '2023-02-07';
DECLARE @__dayOfWeek_1 int = 2;
DECLARE @__time_2 time = '20:14:34.7795877';

SELECT [s].[Id], [s].[Founded], [s].[Name], [s].[OpeningHours]
FROM [Schools] AS [s]
WHERE EXISTS (
    SELECT 1
    FROM [Term] AS [t]
    WHERE [s].[Id] = [t].[SchoolId] AND [t].[FirstDay] <= @__today_0
      AND [t].[LastDay] >= @__today_0)
      AND CAST(JSON_VALUE([s].[OpeningHours],'$[' + CAST(CAST(@__dayOfWeek_1 AS int) AS nvarchar(max)) + '].OpensAt') AS time) < @__time_2
      AND CAST(JSON_VALUE([s].[OpeningHours],'$[' + CAST(CAST(@__dayOfWeek_1 AS int) AS nvarchar(max)) + '].ClosesAt') AS time) >= @__time_2

最後，可以使用追蹤和 SaveChanges 或使用 ExecuteUpdate/ExecuteDelete 來完成更新和刪除。 例如：

await context.Schools
    .Where(e => e.Terms.Any(t => t.LastDay.Year == 2022))
    .SelectMany(e => e.Terms)
    .ExecuteUpdateAsync(s => s.SetProperty(t => t.LastDay, t => t.LastDay.AddDays(1)));

此更新會轉譯為下列 SQL：

UPDATE [t0]
SET [t0].[LastDay] = DATEADD(day, CAST(1 AS int), [t0].[LastDay])
FROM [Schools] AS [s]
INNER JOIN [Term] AS [t0] ON [s].[Id] = [t0].[SchoolId]
WHERE EXISTS (
    SELECT 1
    FROM [Term] AS [t]
    WHERE [s].[Id] = [t].[SchoolId] AND DATEPART(year, [t].[LastDay]) = 2022)

反向工程師 Synapse 和 Dynamics 365 TDS

EF8 反向工程（也就是現有資料庫的 Scaffolding）現在支援 Synapse 無伺服器 SQL 集 區和 Dynamics 365 TDS 端點 資料庫。

數學翻譯的增強功能

.NET 7 中引進了泛型數學 介面。 像是 double 和實作這些介面的具象類型，會新增新的 API，以反映 Math 和 MathF 的現有float功能。

EF Core 8 會使用 和 的現有 SQL 翻譯，在 LINQ 中轉譯這些泛型數學 API 的MathMathF呼叫。 這表示您現在可以在 EF 查詢中自由選擇呼叫，例如 Math.Sin 或 double.Sin 。

我們與 .NET 小組合作，在 和 float上double實作的 .NET 8 中新增兩個新的泛型數學方法。 這些也會轉譯為 EF Core 8 中的 SQL。

最後，我們在 SQLitePCLRaw 專案中與 Eric Sink 合作，在原生 SQLite 連結庫的組建中啟用 SQLite 數學函式。 這包括您在安裝 EF Core SQLite 提供者時預設取得的原生連結庫。 這可在 LINQ 中啟用數個新的 SQL 翻譯，包括：Acos、Acosh、Asin、Asinh、Atan、Atan2、Atanh、Ceiling、Cos、Cosh、DegreesToRadian、Exp、Floor、Log、Log2、Log10、Pow、RadiansToDegrees、Sign、Sin、Sinh、Sqrt、Tan、Tanh 和 Truncate。

檢查暫止的模型變更

我們已新增 dotnet ef 命令，以檢查自上次移轉之後是否有任何模型變更。 這在 CI/CD 案例中很有用，以確保您或小組成員不忘新增移轉。

dotnet ef migrations has-pending-model-changes

您也可以在應用程式中以程式設計方式執行這項檢查，或使用新的 dbContext.Database.HasPendingModelChanges() 方法進行測試。

SQLite Scaffolding 的增強功能

SQLite 僅支援四種基本數據類型：INTEGER、REAL、TEXT 和 BLOB。 先前，這表示當您將 SQLite 資料庫反向設計為 SCaffold EF Core 模型時，產生的實體類型只會包含 、、 string和byte[]類型的longdouble屬性。 EF Core SQLite 提供者支援其他 .NET 類型，方法是在它們與四個基本 SQLite 類型之一之間進行轉換。

在EF Core 8 中，除了 SQLite 類型之外，我們現在還使用數據格式和數據行類型名稱，以判斷模型中要使用的更適當的 .NET 類型。 下表顯示一些案例，其中其他資訊會導致模型中更好的屬性類型。

Sentinel 值和資料庫預設值

如果插入數據列時未提供任何值，資料庫允許數據行設定為產生預設值。 這可以在 EF HasDefaultValue 中使用 常數來表示：

b.Property(e => e.Status).HasDefaultValue("Hidden");

或 HasDefaultValueSql 任意 SQL 子句：

b.Property(e => e.LeaseDate).HasDefaultValueSql("getutcdate()");

為了讓EF能夠使用此專案，它必須判斷何時及何時不傳送數據行的值。 根據預設，EF 會使用CLR預設值做為此的sentinel。 也就是說，當上述範例中的 或 LeaseDate 值Status是這些類型的 CLR 預設值時，EF 會解譯為表示尚未設定屬性，因此不會將值傳送至資料庫。 這適用於參考型別，例如，如果 string 屬性 Status 是 null，則 EF 不會傳送 null 至資料庫，而是不包含任何值，以便使用資料庫預設值 （"Hidden"） 。 同樣地，針對 DateTime 屬性 LeaseDate，EF 不會插入的 CLR 預設值 1/1/0001 12:00:00 AM，而是會省略此值，以便使用資料庫預設值。

不過，在某些情況下，CLR 預設值是插入的有效值。 EF8 會藉由允許數據行的 sentinel 值變更來處理此狀況。 例如，請考慮以資料庫預設值設定的整數數據行：

b.Property(e => e.Credits).HasDefaultValueSql(10);

在此情況下，我們希望新的實體插入指定的點數，除非未指定，在此情況下會指派 10 個點數。 不過，這表示無法插入具有零點數的記錄，因為零是CLR預設值，因此會導致EF不傳送任何值。 在 EF8 中，將 屬性的 sentinel 從零變更為 -1，即可修正此問題：

b.Property(e => e.Credits).HasDefaultValueSql(10).HasSentinel(-1);

如果 Credits 設定為 -1，則 EF 現在只會使用資料庫預設值;將像任何其他數量一樣插入零的值。

在實體類型和 EF 組態中，反映這種情況通常很有用。 例如：

public class Person
{
    public int Id { get; set; }
    public int Credits { get; set; } = -1;
}

這表示在建立實例時，會自動設定 -1 的 sentinel 值，這表示屬性會以其「未設定」狀態啟動。

布爾值的資料庫預設值

布爾值屬性呈現此問題的極端形式，因為CLR預設值只是false兩個有效值的其中一個。 這表示 bool 具有資料庫默認條件約束的屬性只有在該值為 true時才會插入值。 當資料庫預設值為 時，這表示當 屬性值為 falsefalse時，則會使用資料庫預設值，也就是 false。 否則，如果屬性值為 true， true 則會插入 。 因此，當資料庫預設值為 false時，資料庫數據行最後會有正確的值。

另一方面，如果資料庫預設值為 ，這表示當 屬性值為 truefalse時，將會使用資料庫預設值，也就是 true！ 當屬性值為 true時， true 將會插入 。 因此，不論屬性值為何，數據行中的值一律都會在資料庫中結束 true 。

EF8 修正此問題，方法是將bool屬性的sentinel設定為與資料庫預設值相同的值。 此兩種情況都會插入正確的值，不論資料庫預設值為 true 或 false。

列舉的資料庫預設值

列舉屬性可能會有與屬性類似的問題 bool ，因為列舉通常有一組非常小的有效值，而CLR預設值可能是下列其中一個值。 例如，請考慮此實體類型和列舉：

public class Course
{
    public int Id { get; set; }
    public Level Level { get; set; }
}

public enum Level
{
    Beginner,
    Intermediate,
    Advanced,
    Unspecified
}

Level屬性接著使用資料庫預設值設定：

modelBuilder.Entity<Course>()
    .Property(e => e.Level)
    .HasDefaultValue(Level.Intermediate);

使用此組態時，EF 會排除將值設定為 Level.Beginner時傳送至資料庫，而 Level.Intermediate 是由資料庫指派。 這不是原意！

如果列舉定義為資料庫預設值的「未知」或「未指定」值，則不會發生此問題：

public enum Level
{
    Unspecified,
    Beginner,
    Intermediate,
    Advanced
}

不過，不一定可以變更現有的列舉，因此在 EF8 中，可以再次指定 sentinel。 例如，返回原始列舉：

modelBuilder.Entity<Course>()
    .Property(e => e.Level)
    .HasDefaultValue(Level.Intermediate)
    .HasSentinel(Level.Unspecified);

現在 Level.Beginner 會如常插入，而且只有在屬性值為 Level.Unspecified時，才會使用資料庫預設值。 同樣地，在實體類型本身中反映這點可能很有用。 例如：

public class Course
{
    public int Id { get; set; }
    public Level Level { get; set; } = Level.Unspecified;
}

使用可為 Null 的備份欄位

若要處理上述問題的較一般方式，就是為不可為 Null 屬性建立可為 Null 的備份欄位。 例如，請考慮具有 屬性的下列實體類型 bool ：

public class Account
{
    public int Id { get; set; }
    public bool IsActive { get; set; }
}

屬性可以指定可為 Null 的備份欄位：

public class Account
{
    public int Id { get; set; }

    private bool? _isActive;

    public bool IsActive
    {
        get => _isActive ?? false;
        set => _isActive = value;
    }
}

除非實際呼叫屬性 setter，否則此處的備份欄位會維持null不變。 也就是說，備份欄位的值更能指出是否已設定屬性，而不是屬性的CLR預設值。 這與 EF 搭配運作，因為 EF 預設會使用備份字段來讀取和寫入屬性。

Better ExecuteUpdate 和 ExecuteDelete

執行更新和刪除的 SQL 命令，例如和 ExecuteUpdate ExecuteDelete 方法所產生的命令，必須以單一資料庫數據表為目標。 不過，在 EF7 中，即使查詢最終影響單一數據表，ExecuteUpdate也ExecuteDelete不支援存取多個實體類型的更新。 EF8 會移除這項限制。 例如，請考慮 Customer 具有 CustomerInfo 擁有類型的實體類型：

public class Customer
{
    public int Id { get; set; }
    public required string Name { get; set; }
    public required CustomerInfo CustomerInfo { get; set; }
}

[Owned]
public class CustomerInfo
{
    public string? Tag { get; set; }
}

這兩種實體類型都會對應至 Customers 數據表。 不過，EF7 上的下列大量更新失敗，因為它使用這兩種實體類型：

await context.Customers
    .Where(e => e.Name == name)
    .ExecuteUpdateAsync(
        s => s.SetProperty(b => b.CustomerInfo.Tag, "Tagged")
            .SetProperty(b => b.Name, b => b.Name + "_Tagged"));

在 EF8 中，這會在使用 Azure SQL 時轉譯為下列 SQL：

UPDATE [c]
SET [c].[Name] = [c].[Name] + N'_Tagged',
    [c].[CustomerInfo_Tag] = N'Tagged'
FROM [Customers] AS [c]
WHERE [c].[Name] = @__name_0

同樣地，只要更新所有以相同的數據表為目標，就可以更新從 Union 查詢傳回的實例。 例如，我們可以使用 的區域來更新任何 Customer ， France同時，任何 Customer 已使用區域 France流覽商店的人員：

await context.CustomersWithStores
    .Where(e => e.Region == "France")
    .Union(context.Stores.Where(e => e.Region == "France").SelectMany(e => e.Customers))
    .ExecuteUpdateAsync(s => s.SetProperty(b => b.Tag, "The French Connection"));

在 EF8 中，此查詢會在使用 Azure SQL 時產生下列專案：

UPDATE [c]
SET [c].[Tag] = N'The French Connection'
FROM [CustomersWithStores] AS [c]
INNER JOIN (
    SELECT [c0].[Id], [c0].[Name], [c0].[Region], [c0].[StoreId], [c0].[Tag]
    FROM [CustomersWithStores] AS [c0]
    WHERE [c0].[Region] = N'France'
    UNION
    SELECT [c1].[Id], [c1].[Name], [c1].[Region], [c1].[StoreId], [c1].[Tag]
    FROM [Stores] AS [s]
    INNER JOIN [CustomersWithStores] AS [c1] ON [s].[Id] = [c1].[StoreId]
    WHERE [s].[Region] = N'France'
) AS [t] ON [c].[Id] = [t].[Id]

作為最後一個範例，在 EF8 中，只要所有更新的屬性都對應到相同的數據表， ExecuteUpdate 就可以用來更新 TPT 階層中的實體。 例如，請考慮使用 TPT 對應的這些實體類型：

[Table("TptSpecialCustomers")]
public class SpecialCustomerTpt : CustomerTpt
{
    public string? Note { get; set; }
}

[Table("TptCustomers")]
public class CustomerTpt
{
    public int Id { get; set; }
    public required string Name { get; set; }
}

使用 EF8 時， Note 屬性可以更新：

await context.TptSpecialCustomers
    .Where(e => e.Name == name)
    .ExecuteUpdateAsync(s => s.SetProperty(b => b.Note, "Noted"));

Name或者可以更新 屬性：

await context.TptSpecialCustomers
    .Where(e => e.Name == name)
    .ExecuteUpdateAsync(s => s.SetProperty(b => b.Name, b => b.Name + " (Noted)"));

不過，EF8 嘗試同時更新 Name 和 屬性失敗， Note 因為它們會對應至不同的數據表。 例如：

await context.TptSpecialCustomers
    .Where(e => e.Name == name)
    .ExecuteUpdateAsync(s => s.SetProperty(b => b.Note, "Noted")
        .SetProperty(b => b.Name, b => b.Name + " (Noted)"));

擲回下列例外狀況：

The LINQ expression 'DbSet<SpecialCustomerTpt>()
    .Where(s => s.Name == __name_0)
    .ExecuteUpdate(s => s.SetProperty<string>(
        propertyExpression: b => b.Note,
        valueExpression: "Noted").SetProperty<string>(
        propertyExpression: b => b.Name,
        valueExpression: b => b.Name + " (Noted)"))' could not be translated. Additional information: Multiple 'SetProperty' invocations refer to different tables ('b => b.Note' and 'b => b.Name'). A single 'ExecuteUpdate' call can only update the columns of a single table. See https://go.microsoft.com/fwlink/?linkid=2101038 for more information.

更妥善地 IN 使用查詢

Contains當 LINQ 運算子與子查詢搭配使用時，EF Core 現在會使用 SQL 產生更好的查詢，而不是 EXISTS;除了產生更容易閱讀的 SQL IN 之外，在某些情況下，這可能會導致查詢更快。 例如，請考慮下列 LINQ 查詢：

var blogsWithPosts = await context.Blogs
    .Where(b => context.Posts.Select(p => p.BlogId).Contains(b.Id))
    .ToListAsync();

EF7 會針對 PostgreSQL 產生下列專案：

SELECT b."Id", b."Name"
      FROM "Blogs" AS b
      WHERE EXISTS (
          SELECT 1
          FROM "Posts" AS p
          WHERE p."BlogId" = b."Id")

由於子查詢會參考外部 Blogs 數據表（透過 b."Id"），這是 相互關聯的子查詢，這表示 Posts 必須針對數據表中的每個 Blogs 數據列執行子查詢。 在 EF8 中，會改為產生下列 SQL：

SELECT b."Id", b."Name"
      FROM "Blogs" AS b
      WHERE b."Id" IN (
          SELECT p."BlogId"
          FROM "Posts" AS p
      )

由於子查詢不再參考 Blogs，因此可以評估一次，在大部分的資料庫系統上產生大量效能改善。 不過，某些資料庫系統，尤其是 SQL Server，資料庫能夠將第一個查詢優化至第二個查詢，讓效能相同。

SQL Azure/SQL Server 的數值數據列版本

SQL Server 自動開放式並行存取是使用數據rowversion行來處理。 rowversion是資料庫、客戶端和伺服器之間傳遞的8位元組不透明值。 根據預設，SqlClient 會將 rowversion 類型公開為 byte[]，儘管可變動的參考型別與語意不符 rowversion 。 在 EF8 中，您可以輕鬆地將數據行對應 rowversion 至 long 或 ulong 屬性。 例如：

modelBuilder.Entity<Blog>()
    .Property(e => e.RowVersion)
    .IsRowVersion();

括弧消除

產生可讀取的 SQL 是 EF Core 的重要目標。 在EF8中，產生的SQL可透過自動消除不需要的括號來更容易閱讀。 例如，下列 LINQ 查詢：

await ctx.Customers  
    .Where(c => c.Id * 3 + 2 > 0 && c.FirstName != null || c.LastName != null)  
    .ToListAsync();  

使用 EF7 時會轉譯為下列 Azure SQL：

SELECT [c].[Id], [c].[City], [c].[FirstName], [c].[LastName], [c].[Street]
FROM [Customers] AS [c]
WHERE ((([c].[Id] * 3) + 2) > 0 AND ([c].[FirstName] IS NOT NULL)) OR ([c].[LastName] IS NOT NULL)

使用 EF8 時已改善為下列專案：

SELECT [c].[Id], [c].[City], [c].[FirstName], [c].[LastName], [c].[Street]
FROM [Customers] AS [c]
WHERE ([c].[Id] * 3 + 2 > 0 AND [c].[FirstName] IS NOT NULL) OR [c].[LastName] IS NOT NULL

RETURNING/OUTPUT 子句的特定退出

EF7 已變更預設更新 SQL，以用於 RETURNING/OUTPUT 擷取資料庫產生的數據行。 某些發現無法運作的情況，因此 EF8 會針對此行為引入明確的退出。

例如，使用 SQL Server/Azure SQL 提供者時，退出宣告 OUTPUT ：

 modelBuilder.Entity<Customer>().ToTable(tb => tb.UseSqlOutputClause(false));

或者，使用 SQLite 提供者時退出宣告 RETURNING ：

 modelBuilder.Entity<Customer>().ToTable(tb => tb.UseSqlReturningClause(false));

其他次要變更

除了上述的增強功能之外，EF8 還進行了許多較小的變更。 這包括：

• Microsoft.Data.Sqlite 的 NativeAOT/修剪兼容性
• 允許EF Core Cosmos中的多區域或應用程式慣用區域
• SQLite：新增 EF。Functions.Unhex
• SQL Server 索引選項 SortInTempDB 和 DataCompression
• 允許內容之間的「解除共用」連線
• 新增 EntityTypeConfiguration 屬性的一般版本
• 查詢：新增對已撰寫之 JSON 實體投影的支援
• 在集合作業中使用沒有限制/位移的排序時，移除不需要的子查詢和投影
• 允許使用單一服務共用 DbContext
• 選擇性 RestartSequenceOperation.StartValue
• 在非索引鍵屬性上允許UseSequence和HiLo
• 產生「找不到 DbContext」錯誤時，請提供詳細資訊
• 將查詢追蹤行為傳遞至具體化攔截器
• 在 SQL Server 上使用不區分大小寫的字串索引鍵比較
• 允許值轉換器變更 DbType
• 解決EF服務中的應用程式服務
• 允許將 DbConnection 的擁有權從應用程式傳輸至 DbContext