Yang Baru di EF Core 6.0

Artikel
03/27/2023

EF Core 6.0 telah dikirim ke NuGet. Halaman ini berisi gambaran umum perubahan menarik yang diperkenalkan dalam rilis ini.

Tip

Anda dapat menjalankan dan men-debug ke dalam sampel yang ditunjukkan di bawah ini dengan mengunduh kode sampel dari GitHub.

Tabel temporal SQL Server

Masalah GitHub: #4693.

Tabel temporal SQL Server secara otomatis melacak semua data yang pernah disimpan dalam tabel, bahkan setelah data tersebut diperbarui atau dihapus. Ini dicapai dengan membuat "tabel riwayat" paralel tempat data historis bertanda waktu disimpan setiap kali perubahan dilakukan pada tabel utama. Ini memungkinkan data historis untuk dikueri, seperti untuk audit, atau dipulihkan, seperti untuk pemulihan setelah mutasi atau penghapusan yang tidak disengaja.

EF Core sekarang mendukung:

Pembuatan tabel temporal menggunakan Migrasi
Transformasi tabel yang ada menjadi tabel temporal, sekali lagi menggunakan Migrasi
Mengkueri data historis
Memulihkan data dari beberapa titik di masa lalu

Mengonfigurasi tabel temporal

Pembuat model dapat digunakan untuk mengonfigurasi tabel sebagai temporal. Contohnya:

modelBuilder
    .Entity<Employee>()
    .ToTable("Employees", b => b.IsTemporal());

Saat menggunakan EF Core untuk membuat database, tabel baru akan dikonfigurasi sebagai tabel temporal dengan default SQL Server untuk tanda waktu dan tabel riwayat. Misalnya, pertimbangkan Employee jenis entitas:

public class Employee
{
    public Guid EmployeeId { get; set; }
    public string Name { get; set; }
    public string Position { get; set; }
    public string Department { get; set; }
    public string Address { get; set; }
    public decimal AnnualSalary { get; set; }
}

Tabel temporal yang dibuat akan terlihat seperti ini:

DECLARE @historyTableSchema sysname = SCHEMA_NAME()
EXEC(N'CREATE TABLE [Employees] (
    [EmployeeId] uniqueidentifier NOT NULL,
    [Name] nvarchar(100) NULL,
    [Position] nvarchar(100) NULL,
    [Department] nvarchar(100) NULL,
    [Address] nvarchar(1024) NULL,
    [AnnualSalary] decimal(10,2) NOT NULL,
    [PeriodEnd] datetime2 GENERATED ALWAYS AS ROW END NOT NULL,
    [PeriodStart] datetime2 GENERATED ALWAYS AS ROW START NOT NULL,
    CONSTRAINT [PK_Employees] PRIMARY KEY ([EmployeeId]),
    PERIOD FOR SYSTEM_TIME([PeriodStart], [PeriodEnd])
) WITH (SYSTEM_VERSIONING = ON (HISTORY_TABLE = [' + @historyTableSchema + N'].[EmployeeHistory]))');

Perhatikan bahwa SQL Server membuat dua kolom tersembunyi datetime2 yang disebut PeriodEnd dan PeriodStart. "Kolom titik" ini mewakili rentang waktu di mana data dalam baris ada. Kolom ini dipetakan ke properti bayangan dalam model EF Core, memungkinkannya digunakan dalam kueri seperti yang ditunjukkan nanti.

Penting

Waktu dalam kolom ini selalu waktu UTC yang dihasilkan oleh SQL Server. Waktu UTC digunakan untuk semua operasi yang melibatkan tabel temporal, seperti dalam kueri yang ditunjukkan di bawah ini.

Perhatikan juga bahwa tabel riwayat terkait yang disebut EmployeeHistory dibuat secara otomatis. Nama kolom periode dan tabel riwayat dapat diubah dengan konfigurasi tambahan ke penyusun model. Contohnya:

modelBuilder
    .Entity<Employee>()
    .ToTable(
        "Employees",
        b => b.IsTemporal(
            b =>
            {
                b.HasPeriodStart("ValidFrom");
                b.HasPeriodEnd("ValidTo");
                b.UseHistoryTable("EmployeeHistoricalData");
            }));

Ini tercermin dalam tabel yang dibuat oleh SQL Server:

DECLARE @historyTableSchema sysname = SCHEMA_NAME()
EXEC(N'CREATE TABLE [Employees] (
    [EmployeeId] uniqueidentifier NOT NULL,
    [Name] nvarchar(100) NULL,
    [Position] nvarchar(100) NULL,
    [Department] nvarchar(100) NULL,
    [Address] nvarchar(1024) NULL,
    [AnnualSalary] decimal(10,2) NOT NULL,
    [ValidFrom] datetime2 GENERATED ALWAYS AS ROW START NOT NULL,
    [ValidTo] datetime2 GENERATED ALWAYS AS ROW END NOT NULL,
    CONSTRAINT [PK_Employees] PRIMARY KEY ([EmployeeId]),
    PERIOD FOR SYSTEM_TIME([ValidFrom], [ValidTo])
) WITH (SYSTEM_VERSIONING = ON (HISTORY_TABLE = [' + @historyTableSchema + N'].[EmployeeHistoricalData]))');

Menggunakan tabel temporal

Sebagian besar waktu, tabel temporal digunakan sama seperti tabel lainnya. Artinya, kolom periode dan data historis ditangani secara transparan oleh SQL Server sehingga aplikasi dapat mengabaikannya. Misalnya, entitas baru dapat disimpan ke database dengan cara normal:

context.AddRange(
    new Employee
    {
        Name = "Pinky Pie",
        Address = "Sugarcube Corner, Ponyville, Equestria",
        Department = "DevDiv",
        Position = "Party Organizer",
        AnnualSalary = 100.0m
    },
    new Employee
    {
        Name = "Rainbow Dash",
        Address = "Cloudominium, Ponyville, Equestria",
        Department = "DevDiv",
        Position = "Ponyville weather patrol",
        AnnualSalary = 900.0m
    },
    new Employee
    {
        Name = "Fluttershy",
        Address = "Everfree Forest, Equestria",
        Department = "DevDiv",
        Position = "Animal caretaker",
        AnnualSalary = 30.0m
    });

context.SaveChanges();

Data ini kemudian dapat dikueri, diperbarui, dan dihapus dengan cara normal. Contohnya:

var employee = context.Employees.Single(e => e.Name == "Rainbow Dash");
context.Remove(employee);
context.SaveChanges();

Selain itu, setelah kueri pelacakan normal, nilai dari kolom periode data saat ini dapat diakses dari entitas yang dilacak. Contohnya:

var employees = context.Employees.ToList();
foreach (var employee in employees)
{
    var employeeEntry = context.Entry(employee);
    var validFrom = employeeEntry.Property<DateTime>("ValidFrom").CurrentValue;
    var validTo = employeeEntry.Property<DateTime>("ValidTo").CurrentValue;

    Console.WriteLine($"  Employee {employee.Name} valid from {validFrom} to {validTo}");
}

Cetakan ini:

Starting data:
  Employee Pinky Pie valid from 8/26/2021 4:38:58 PM to 12/31/9999 11:59:59 PM
  Employee Rainbow Dash valid from 8/26/2021 4:38:58 PM to 12/31/9999 11:59:59 PM
  Employee Fluttershy valid from 8/26/2021 4:38:58 PM to 12/31/9999 11:59:59 PM

Perhatikan bahwa ValidTo kolom (secara default disebut PeriodEnd) berisi datetime2 nilai maks. Ini selalu terjadi untuk baris saat ini dalam tabel. Kolom ValidFrom (secara default disebut PeriodStart) berisi waktu UTC yang disisipkan baris.

Mengkueri data historis

EF Core mendukung kueri yang menyertakan data historis melalui beberapa operator kueri baru:

TemporalAsOf: Mengembalikan baris yang aktif (saat ini) pada waktu UTC yang diberikan. Ini adalah satu baris dari tabel atau tabel riwayat saat ini untuk kunci primer tertentu.
TemporalAll: Mengembalikan semua baris dalam data historis. Ini biasanya banyak baris dari tabel riwayat dan/atau tabel saat ini untuk kunci primer tertentu.
TemporalFromTo: Mengembalikan semua baris yang aktif di antara dua waktu UTC tertentu. Ini mungkin banyak baris dari tabel riwayat dan/atau tabel saat ini untuk kunci primer tertentu.
TemporalBetween: Sama seperti TemporalFromTo, kecuali bahwa baris disertakan yang menjadi aktif di batas atas.
TemporalContainedIn: Mengembalikan semua baris yang mulai aktif dan berakhir aktif di antara dua waktu UTC yang diberikan. Ini mungkin banyak baris dari tabel riwayat dan/atau tabel saat ini untuk kunci primer tertentu.

Catatan

Lihat dokumentasi tabel temporal SQL Server untuk informasi selengkapnya tentang baris mana yang disertakan untuk masing-masing operator ini.

Misalnya, setelah membuat beberapa pembaruan dan menghapus data kami, kita dapat menjalankan kueri menggunakan TemporalAll untuk melihat data historis:

var history = context
    .Employees
    .TemporalAll()
    .Where(e => e.Name == "Rainbow Dash")
    .OrderBy(e => EF.Property<DateTime>(e, "ValidFrom"))
    .Select(
        e => new
        {
            Employee = e,
            ValidFrom = EF.Property<DateTime>(e, "ValidFrom"),
            ValidTo = EF.Property<DateTime>(e, "ValidTo")
        })
    .ToList();

foreach (var pointInTime in history)
{
    Console.WriteLine(
        $"  Employee {pointInTime.Employee.Name} was '{pointInTime.Employee.Position}' from {pointInTime.ValidFrom} to {pointInTime.ValidTo}");
}

Perhatikan bagaimana EF. Metode properti dapat digunakan untuk mengakses nilai dari kolom periode. Ini digunakan dalam OrderBy klausul untuk mengurutkan data, lalu dalam proyeksi untuk menyertakan nilai-nilai ini dalam data yang dikembalikan.

Kueri ini mengembalikan data berikut:

Historical data for Rainbow Dash:
  Employee Rainbow Dash was 'Ponyville weather patrol' from 8/26/2021 4:38:58 PM to 8/26/2021 4:40:29 PM
  Employee Rainbow Dash was 'Wonderbolt Trainee' from 8/26/2021 4:40:29 PM to 8/26/2021 4:41:59 PM
  Employee Rainbow Dash was 'Wonderbolt Reservist' from 8/26/2021 4:41:59 PM to 8/26/2021 4:43:29 PM
  Employee Rainbow Dash was 'Wonderbolt' from 8/26/2021 4:43:29 PM to 8/26/2021 4:44:59 PM

Perhatikan bahwa baris terakhir yang dikembalikan berhenti aktif pada 26/8/2021 16:44:59 PM. Ini karena baris untuk Rainbow Dash dihapus dari tabel utama pada saat itu. Kita akan melihat nanti bagaimana data ini dapat dipulihkan.

Kueri serupa dapat ditulis menggunakan TemporalFromTo, , TemporalBetweenatau TemporalContainedIn. Contohnya:

var history = context
    .Employees
    .TemporalBetween(timeStamp2, timeStamp3)
    .Where(e => e.Name == "Rainbow Dash")
    .OrderBy(e => EF.Property<DateTime>(e, "ValidFrom"))
    .Select(
        e => new
        {
            Employee = e,
            ValidFrom = EF.Property<DateTime>(e, "ValidFrom"),
            ValidTo = EF.Property<DateTime>(e, "ValidTo")
        })
    .ToList();

Kueri ini mengembalikan baris berikut:

Historical data for Rainbow Dash between 8/26/2021 4:41:14 PM and 8/26/2021 4:42:44 PM:
  Employee Rainbow Dash was 'Wonderbolt Trainee' from 8/26/2021 4:40:29 PM to 8/26/2021 4:41:59 PM
  Employee Rainbow Dash was 'Wonderbolt Reservist' from 8/26/2021 4:41:59 PM to 8/26/2021 4:43:29 PM

Memulihkan data historis

Seperti disebutkan di atas, Rainbow Dash dihapus dari Employees tabel. Ini jelas merupakan kesalahan, jadi mari kita kembali ke titik waktu dan memulihkan baris yang hilang dari waktu itu.

var employee = context
    .Employees
    .TemporalAsOf(timeStamp2)
    .Single(e => e.Name == "Rainbow Dash");

context.Add(employee);
context.SaveChanges();

Kueri ini mengembalikan satu baris untuk Rainbow Dash seperti pada waktu UTC yang diberikan. Semua kueri yang menggunakan operator temporal tidak dilacak secara default, sehingga entitas yang dikembalikan di sini tidak dilacak. Ini masuk akal, karena saat ini tidak ada di tabel utama. Untuk memasukkan kembali entitas ke dalam tabel utama, kita cukup menandainya sebagai Added dan kemudian memanggil SaveChanges.

Setelah menyisipkan ulang baris Rainbow Dash, mengkueri data historis menunjukkan bahwa baris dipulihkan seperti pada waktu UTC yang diberikan:

Historical data for Rainbow Dash:
  Employee Rainbow Dash was 'Ponyville weather patrol' from 8/26/2021 4:38:58 PM to 8/26/2021 4:40:29 PM
  Employee Rainbow Dash was 'Wonderbolt Trainee' from 8/26/2021 4:40:29 PM to 8/26/2021 4:41:59 PM
  Employee Rainbow Dash was 'Wonderbolt Reservist' from 8/26/2021 4:41:59 PM to 8/26/2021 4:43:29 PM
  Employee Rainbow Dash was 'Wonderbolt' from 8/26/2021 4:43:29 PM to 8/26/2021 4:44:59 PM
  Employee Rainbow Dash was 'Wonderbolt Trainee' from 8/26/2021 4:44:59 PM to 12/31/9999 11:59:59 PM

Bundel Migrasi

Masalah GitHub: #19693.

Migrasi EF Core digunakan untuk menghasilkan pembaruan skema database berdasarkan perubahan pada model EF. Pembaruan skema ini harus diterapkan pada waktu penyebaran aplikasi, seringkali sebagai bagian dari sistem integrasi berkelanjutan/penyebaran berkelanjutan (C.I./C.D.).

EF Core sekarang menyertakan cara baru untuk menerapkan pembaruan skema ini: bundel migrasi. Bundel migrasi adalah migrasi kecil yang dapat dieksekusi yang berisi migrasi dan kode yang diperlukan untuk menerapkan migrasi ini ke database.

Catatan

Lihat Memperkenalkan Bundel Migrasi Inti EF yang ramah DevOps di Blog .NET untuk diskusi yang lebih mendalam tentang migrasi, bundel, dan penyebaran.

Bundel migrasi dibuat menggunakan dotnet ef alat baris perintah. Pastikan Anda telah menginstal versi terbaru alat sebelum melanjutkan.

Bundel memerlukan migrasi untuk disertakan. Ini dibuat menggunakan dotnet ef migrations add seperti yang dijelaskan dalam dokumentasi migrasi. Setelah Anda memiliki migrasi yang siap disebarkan, buat bundel menggunakan dotnet ef migrations bundle. Contohnya:

PS C:\local\AllTogetherNow\SixOh> dotnet ef migrations bundle
Build started...
Build succeeded.
Building bundle...
Done. Migrations Bundle: C:\local\AllTogetherNow\SixOh\efbundle.exe
PS C:\local\AllTogetherNow\SixOh>

Output adalah executable yang cocok untuk sistem operasi target Anda. Dalam kasus saya ini adalah Windows x64, jadi saya mendapatkan dihilangkan efbundle.exe di folder lokal saya. Menjalankan executable ini menerapkan migrasi yang terkandung di dalamnya:

PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe
Applying migration '20210903083845_MyMigration'.
Done.
PS C:\local\AllTogetherNow\SixOh>

Migrasi diterapkan ke database hanya jika belum diterapkan. Misalnya, menjalankan bundel yang sama lagi tidak melakukan apa-apa, karena tidak ada migrasi baru untuk diterapkan:

PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe
No migrations were applied. The database is already up to date.
Done.
PS C:\local\AllTogetherNow\SixOh>

Namun, jika perubahan dilakukan pada model dan lebih banyak migrasi dihasilkan dengan dotnet ef migrations add, maka ini dapat dibundel ke dalam executable baru yang siap diterapkan. Contohnya:

PS C:\local\AllTogetherNow\SixOh> dotnet ef migrations add SecondMigration
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'
PS C:\local\AllTogetherNow\SixOh> dotnet ef migrations add Number3
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'
PS C:\local\AllTogetherNow\SixOh> dotnet ef migrations bundle --force
Build started...
Build succeeded.
Building bundle...
Done. Migrations Bundle: C:\local\AllTogetherNow\SixOh\efbundle.exe
PS C:\local\AllTogetherNow\SixOh>

Perhatikan bahwa --force opsi dapat digunakan untuk menimpa bundel yang ada dengan yang baru.

Menjalankan bundel baru ini menerapkan dua migrasi baru ini ke database:

PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe
Applying migration '20210903084526_SecondMigration'.
Applying migration '20210903084538_Number3'.
Done.
PS C:\local\AllTogetherNow\SixOh>

Secara default, bundel menggunakan database string koneksi dari konfigurasi aplikasi Anda. Namun, database yang berbeda dapat dimigrasikan dengan melewati string koneksi pada baris perintah. Contohnya:

PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe --connection "Data Source=(LocalDb)\MSSQLLocalDB;Database=SixOhProduction"
Applying migration '20210903083845_MyMigration'.
Applying migration '20210903084526_SecondMigration'.
Applying migration '20210903084538_Number3'.
Done.
PS C:\local\AllTogetherNow\SixOh>

Perhatikan bahwa kali ini ketiga migrasi diterapkan, karena belum ada yang diterapkan ke database produksi.

Opsi lain dapat diteruskan ke baris perintah. Beberapa opsi umum adalah:

--output untuk menentukan jalur file yang dapat dieksekusi untuk dibuat.
--context untuk menentukan jenis DbContext yang akan digunakan saat proyek berisi beberapa jenis konteks.
--project untuk menentukan proyek yang akan digunakan. Default ke direktori kerja saat ini.
--startup-project untuk menentukan proyek startup yang akan digunakan. Default ke direktori kerja saat ini.
--no-build untuk mencegah proyek dibangun sebelum menjalankan perintah. Ini hanya boleh digunakan jika proyek diketahui sudah diperbarui.
--verbose untuk melihat informasi terperinci tentang apa yang dilakukan perintah. Gunakan opsi ini saat menyertakan informasi dalam laporan bug.

Gunakan dotnet ef migrations bundle --help untuk melihat semua opsi yang tersedia.

Perhatikan bahwa secara default setiap migrasi diterapkan dalam transaksinya sendiri. Lihat masalah GitHub #22616 untuk diskusi tentang kemungkinan peningkatan di masa mendatang di area ini.

Konfigurasi model pra-konvensi

Masalah GitHub: #12229.

Versi EF Core sebelumnya mengharuskan pemetaan untuk setiap properti dari jenis tertentu dikonfigurasi secara eksplisit ketika pemetaan tersebut berbeda dari default. Ini termasuk "faset" seperti panjang maksimum string dan presisi desimal, serta konversi nilai untuk jenis properti.

Hal ini juga harus:

Konfigurasi pembuat model untuk setiap properti
Atribut pemetaan pada setiap properti
Perulangan eksplisit atas semua properti semua jenis entitas dan penggunaan API metadata tingkat rendah saat membangun model.

Perhatikan bahwa iterasi eksplisit rawan kesalahan dan sulit dilakukan dengan kuat karena daftar jenis entitas dan properti yang dipetakan mungkin tidak final pada saat iterasi ini terjadi.

EF Core 6.0 memungkinkan konfigurasi pemetaan ini ditentukan sekali untuk jenis tertentu. Kemudian akan diterapkan ke semua properti jenis tersebut dalam model. Ini disebut "konfigurasi model pra-konvensi", karena mengonfigurasi aspek model yang kemudian digunakan oleh konvensi pembuatan model. Konfigurasi tersebut diterapkan dengan mengambil alih ConfigureConventions pada :DbContext

public class SomeDbContext : DbContext
{
    protected override void ConfigureConventions(
        ModelConfigurationBuilder configurationBuilder)
    {
        // Pre-convention model configuration goes here
    }
}

Misalnya, pertimbangkan jenis entitas berikut:

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }
    public bool IsActive { get; set; }
    public Money AccountValue { get; set; }

    public Session CurrentSession { get; set; }

    public ICollection<Order> Orders { get; } = new List<Order>();
}

public class Order
{
    public int Id { get; set; }
    public string SpecialInstructions { get; set; }
    public DateTime OrderDate { get; set; }
    public bool IsComplete { get; set; }
    public Money Price { get; set; }
    public Money? Discount { get; set; }

    public Customer Customer { get; set; }
}

Semua properti string dapat dikonfigurasi menjadi ANSI (bukan Unicode) dan memiliki panjang maksimum 1024:

configurationBuilder
    .Properties<string>()
    .AreUnicode(false)
    .HaveMaxLength(1024);

Semua properti DateTime dapat dikonversi ke bilangan bulat 64-bit dalam database, menggunakan konversi default dari DateTimes ke longs:

configurationBuilder
    .Properties<DateTime>()
    .HaveConversion<long>();

Semua properti bool dapat dikonversi ke bilangan 0 bulat atau 1 menggunakan salah satu pengonversi nilai bawaan:

configurationBuilder
    .Properties<bool>()
    .HaveConversion<BoolToZeroOneConverter<int>>();

Dengan asumsi Session adalah properti sementara entitas dan tidak boleh dipertahankan, itu dapat diabaikan di mana-mana dalam model:

configurationBuilder
    .IgnoreAny<Session>();

Konfigurasi model pra-konvensi sangat berguna saat bekerja dengan objek nilai. Misalnya, jenis Money dalam model di atas diwakili oleh struktur baca-saja:

public readonly struct Money
{
    [JsonConstructor]
    public Money(decimal amount, Currency currency)
    {
        Amount = amount;
        Currency = currency;
    }

    public override string ToString()
        => (Currency == Currency.UsDollars ? "$" : "£") + Amount;

    public decimal Amount { get; }
    public Currency Currency { get; }
}

public enum Currency
{
    UsDollars,
    PoundsSterling
}

Ini kemudian diserialisasikan ke dan dari JSON menggunakan pengonversi nilai kustom:

public class MoneyConverter : ValueConverter<Money, string>
{
    public MoneyConverter()
        : base(
            v => JsonSerializer.Serialize(v, (JsonSerializerOptions)null),
            v => JsonSerializer.Deserialize<Money>(v, (JsonSerializerOptions)null))
    {
    }
}

Pengonversi nilai ini dapat dikonfigurasi sekali untuk semua penggunaan Uang:

configurationBuilder
    .Properties<Money>()
    .HaveConversion<MoneyConverter>()
    .HaveMaxLength(64);

Perhatikan juga bahwa faset tambahan dapat ditentukan untuk kolom string tempat JSON serial disimpan. Dalam hal ini, kolom dibatasi hingga panjang maksimum 64.

Tabel yang dibuat untuk SQL Server menggunakan migrasi menunjukkan bagaimana konfigurasi telah diterapkan ke semua kolom yang dipetakan:

CREATE TABLE [Customers] (
    [Id] int NOT NULL IDENTITY,
    [Name] varchar(1024) NULL,
    [IsActive] int NOT NULL,
    [AccountValue] nvarchar(64) NOT NULL,
    CONSTRAINT [PK_Customers] PRIMARY KEY ([Id])
);
CREATE TABLE [Order] (
    [Id] int NOT NULL IDENTITY,
    [SpecialInstructions] varchar(1024) NULL,
    [OrderDate] bigint NOT NULL,
    [IsComplete] int NOT NULL,
    [Price] nvarchar(64) NOT NULL,
    [Discount] nvarchar(64) NULL,
    [CustomerId] int NULL,
    CONSTRAINT [PK_Order] PRIMARY KEY ([Id]),
    CONSTRAINT [FK_Order_Customers_CustomerId] FOREIGN KEY ([CustomerId]) REFERENCES [Customers] ([Id])
);

Dimungkinkan juga untuk menentukan pemetaan jenis default untuk jenis tertentu. Contohnya:

configurationBuilder
    .DefaultTypeMapping<string>()
    .IsUnicode(false);

Ini jarang diperlukan, tetapi dapat berguna jika jenis digunakan dalam kueri dengan cara yang tidak terkait dengan properti model yang dipetakan.

Catatan

Lihat Mengumumkan Entity Framework Core 6.0 Preview 6: Mengonfigurasi Konvensi di Blog .NET untuk diskusi dan contoh konfigurasi model pra-konvensi lebih lanjut.

Model yang dikompilasi

Masalah GitHub: #1906.

Model yang dikompilasi dapat meningkatkan waktu mulai EF Core untuk aplikasi dengan model besar. Model besar biasanya berarti 100 hingga 1000-an jenis dan hubungan entitas.

Waktu mulai berarti waktu untuk melakukan operasi pertama pada DbContext ketika jenis DbContext digunakan untuk pertama kalinya dalam aplikasi. Perhatikan bahwa hanya membuat instans DbContext tidak menyebabkan model EF diinisialisasi. Sebagai gantinya, operasi pertama umum yang menyebabkan model diinisialisasi termasuk memanggil DbContext.Add atau menjalankan kueri pertama.

Model yang dikompilasi dibuat menggunakan dotnet ef alat baris perintah. Pastikan Anda telah menginstal versi terbaru alat sebelum melanjutkan.

Perintah baru dbcontext optimize digunakan untuk menghasilkan model yang dikompilasi. Contohnya:

dotnet ef dbcontext optimize

Opsi --output-dir dan --namespace dapat digunakan untuk menentukan direktori dan namespace tempat model yang dikompilasi akan dihasilkan. Contohnya:

PS C:\dotnet\efdocs\samples\core\Miscellaneous\CompiledModels> dotnet ef dbcontext optimize --output-dir MyCompiledModels --namespace MyCompiledModels
Build started...
Build succeeded.
Successfully generated a compiled model, to use it call 'options.UseModel(MyCompiledModels.BlogsContextModel.Instance)'. Run this command again when the model is modified.
PS C:\dotnet\efdocs\samples\core\Miscellaneous\CompiledModels>

Output dari menjalankan perintah ini mencakup sepotong kode untuk disalin dan ditempelkan ke konfigurasi DbContext Anda untuk menyebabkan EF Core menggunakan model yang dikompilasi. Contohnya:

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    => optionsBuilder
        .UseModel(MyCompiledModels.BlogsContextModel.Instance)
        .UseSqlite(@"Data Source=test.db");

Bootstrapping model yang dikompilasi

Biasanya tidak perlu melihat kode bootstrapping yang dihasilkan. Namun, terkadang dapat berguna untuk menyesuaikan model atau pemuatannya. Kode bootstrapping terlihat seperti ini:

[DbContext(typeof(BlogsContext))]
partial class BlogsContextModel : RuntimeModel
{
    private static BlogsContextModel _instance;
    public static IModel Instance
    {
        get
        {
            if (_instance == null)
            {
                _instance = new BlogsContextModel();
                _instance.Initialize();
                _instance.Customize();
            }

            return _instance;
        }
    }

    partial void Initialize();

    partial void Customize();
}

Ini adalah kelas parsial dengan metode parsial yang dapat diimplementasikan untuk menyesuaikan model sesuai kebutuhan.

Selain itu, beberapa model yang dikompilasi dapat dihasilkan untuk jenis DbContext yang dapat menggunakan model yang berbeda tergantung pada beberapa konfigurasi runtime. Ini harus ditempatkan ke dalam folder dan namespace yang berbeda, seperti yang ditunjukkan di atas. Informasi runtime, seperti string koneksi, kemudian dapat diperiksa dan model yang benar dikembalikan sesuai kebutuhan. Contohnya:

public static class RuntimeModelCache
{
    private static readonly ConcurrentDictionary<string, IModel> _runtimeModels
        = new();

    public static IModel GetOrCreateModel(string connectionString)
        => _runtimeModels.GetOrAdd(
            connectionString, cs =>
            {
                if (cs.Contains("X"))
                {
                    return BlogsContextModel1.Instance;
                }

                if (cs.Contains("Y"))
                {
                    return BlogsContextModel2.Instance;
                }

                throw new InvalidOperationException("No appropriate compiled model found.");
            });
}

Batasan

Model yang dikompilasi memiliki beberapa batasan:

Filter kueri global tidak didukung.
Proksi pemuatan dan pelacakan perubahan malas tidak didukung.
Implementasi IModelCacheKeyFactory kustom tidak didukung. Namun, Anda dapat mengkompilasi beberapa model dan memuat model yang sesuai kebutuhan.
Model harus disinkronkan secara manual dengan meregenerasinya kapan saja definisi model atau perubahan konfigurasi.

Karena keterbatasan ini, Anda hanya boleh menggunakan model yang dikompilasi jika waktu mulai EF Core Anda terlalu lambat. Mengkompilasi model kecil biasanya tidak sepadan.

Jika mendukung salah satu fitur ini sangat penting untuk keberhasilan Anda, pilih masalah yang sesuai yang ditautkan di atas.

Tolak ukur

Tip

Anda dapat mencoba mengompilasi model besar dan menjalankan tolok ukur di atasnya dengan mengunduh kode sampel dari GitHub.

Model dalam repositori GitHub yang direferensikan di atas berisi 449 jenis entitas, 6390 properti, dan 720 hubungan. Ini adalah model yang cukup besar. Menggunakan BenchmarkDotNet untuk mengukur, waktu rata-rata untuk kueri pertama adalah 1,02 detik pada laptop yang cukup kuat. Menggunakan model yang dikompilasi menurunkan ini ke 117 milidetik pada perangkat keras yang sama. Peningkatan 8x hingga 10x seperti ini tetap relatif konstan saat ukuran model meningkat.

Compiled model performance improvement

Catatan

Lihat Mengumumkan Entity Framework Core 6.0 Preview 5: Model yang Dikompilasi di Blog .NET untuk diskusi yang lebih mendalam tentang performa startup EF Core dan model yang dikompilasi.

Peningkatan performa pada TechEmpower Fortunes

Masalah GitHub: #23611.

Kami melakukan peningkatan signifikan pada performa kueri untuk EF Core 6.0. Khususnya:

Performa EF Core 6.0 sekarang 70% lebih cepat pada tolok ukur TechEmpower Fortunes standar industri, dibandingkan dengan 5,0.
- Ini adalah peningkatan perf tumpukan penuh, termasuk peningkatan dalam kode tolok ukur, runtime .NET, dll.
EF Core 6.0 sendiri 31% lebih cepat mengeksekusi kueri yang tidak terlacak.
Alokasi timbunan telah dikurangi sebesar 43% saat menjalankan kueri.

Setelah peningkatan ini, kesenjangan antara Dapper "micro-ORM" yang populer dan EF Core dalam tolok ukur TechEmpower Fortunes dipersempit dari 55% menjadi sekitar sedikit di bawah 5%.

Catatan

Lihat Mengumumkan Entity Framework Core 6.0 Pratinjau 4: Edisi Performa di Blog .NET untuk diskusi terperinci tentang peningkatan performa kueri di EF Core 6.0.

Penyempurnaan penyedia Azure Cosmos DB

EF Core 6.0 berisi banyak peningkatan pada penyedia database Azure Cosmos DB.

Tip

Anda dapat menjalankan dan men-debug ke semua sampel khusus Cosmos dengan mengunduh kode sampel dari GitHub.

Default ke kepemilikan implisit

Masalah GitHub: #24803.

Saat membangun model untuk penyedia Azure Cosmos DB, EF Core 6.0 akan menandai jenis entitas anak sebagai milik entitas induk mereka secara default. Ini menghapus kebutuhan akan banyak OwnsMany panggilan dan OwnsOne dalam model Azure Cosmos DB. Ini membuatnya lebih mudah untuk menyematkan jenis anak ke dalam dokumen untuk jenis induk, yang biasanya merupakan cara yang tepat untuk memodelkan orang tua dan anak dalam database dokumen.

Misalnya, pertimbangkan jenis entitas ini:

public class Family
{
    [JsonPropertyName("id")]
    public string Id { get; set; }

    public string LastName { get; set; }
    public bool IsRegistered { get; set; }

    public Address Address { get; set; }

    public IList<Parent> Parents { get; } = new List<Parent>();
    public IList<Child> Children { get; } = new List<Child>();
}

public class Parent
{
    public string FamilyName { get; set; }
    public string FirstName { get; set; }
}

public class Child
{
    public string FamilyName { get; set; }
    public string FirstName { get; set; }
    public int Grade { get; set; }

    public string Gender { get; set; }

    public IList<Pet> Pets { get; } = new List<Pet>();
}

Dalam EF Core 5.0, jenis ini akan dimodelkan untuk Azure Cosmos DB dengan konfigurasi berikut:

modelBuilder.Entity<Family>()
    .HasPartitionKey(e => e.LastName)
    .OwnsMany(f => f.Parents);

modelBuilder.Entity<Family>()
    .OwnsMany(f => f.Children)
    .OwnsMany(c => c.Pets);

modelBuilder.Entity<Family>()
    .OwnsOne(f => f.Address);

Dalam EF Core 6.0, kepemilikannya implisit, mengurangi konfigurasi model menjadi:

modelBuilder.Entity<Family>().HasPartitionKey(e => e.LastName);

Dokumen Azure Cosmos DB yang dihasilkan memiliki orang tua, anak, hewan peliharaan, dan alamat keluarga yang disematkan dalam dokumen keluarga. Contoh:

{
  "Id": "Wakefield.7",
  "LastName": "Wakefield",
  "Discriminator": "Family",
  "IsRegistered": true,
  "id": "Family|Wakefield.7",
  "Address": {
    "City": "NY",
    "County": "Manhattan",
    "State": "NY"
  },
  "Children": [
    {
      "FamilyName": "Merriam",
      "FirstName": "Jesse",
      "Gender": "female",
      "Grade": 8,
      "Pets": [
        {
          "GivenName": "Goofy"
        },
        {
          "GivenName": "Shadow"
        }
      ]
    },
    {
      "FamilyName": "Miller",
      "FirstName": "Lisa",
      "Gender": "female",
      "Grade": 1,
      "Pets": []
    }
  ],
  "Parents": [
    {
      "FamilyName": "Wakefield",
      "FirstName": "Robin"
    },
    {
      "FamilyName": "Miller",
      "FirstName": "Ben"
    }
  ],
  "_rid": "x918AKh6p20CAAAAAAAAAA==",
  "_self": "dbs/x918AA==/colls/x918AKh6p20=/docs/x918AKh6p20CAAAAAAAAAA==/",
  "_etag": "\"00000000-0000-0000-adee-87f30c8c01d7\"",
  "_attachments": "attachments/",
  "_ts": 1632121802
}

Catatan

Penting untuk diingat OwnsOne/OwnsMany bahwa konfigurasi harus digunakan jika Anda perlu mengonfigurasi lebih lanjut jenis yang dimiliki ini.

Koleksi jenis primitif

Masalah GitHub: #14762.

EF Core 6.0 secara asli memetakan koleksi jenis primitif saat menggunakan penyedia database Azure Cosmos DB. Misalnya, pertimbangkan jenis entitas ini:

public class Book
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public IList<string> Quotes { get; set; }
    public IDictionary<string, string> Notes { get; set; }
}

Daftar dan kamus dapat diisi dan disisipkan ke dalam database dengan cara konvensional:

using var context = new BooksContext();

var book = new Book
{
    Title = "How It Works: Incredible History",
    Quotes = new List<string>
    {
        "Thomas (Tommy) Flowers was the British engineer behind the design of the Colossus computer.",
        "Invented originally for Guinness, plastic widgets are nitrogen-filled spheres.",
        "For 20 years after its introduction in 1979, the Walkman dominated the personal stereo market."
    },
    Notes = new Dictionary<string, string>
    {
        { "121", "Fridges" },
        { "144", "Peter Higgs" },
        { "48", "Saint Mark's Basilica" },
        { "36", "The Terracotta Army" }
    }
};

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

Ini menghasilkan dokumen JSON berikut:

{
    "Id": "0b32283e-22a8-4103-bb4f-6052604868bd",
    "Discriminator": "Book",
    "Notes": {
        "36": "The Terracotta Army",
        "48": "Saint Mark's Basilica",
        "121": "Fridges",
        "144": "Peter Higgs"
    },
    "Quotes": [
        "Thomas (Tommy) Flowers was the British engineer behind the design of the Colossus computer.",
        "Invented originally for Guinness, plastic widgets are nitrogen-filled spheres.",
        "For 20 years after its introduction in 1979, the Walkman dominated the personal stereo market."
    ],
    "Title": "How It Works: Incredible History",
    "id": "Book|0b32283e-22a8-4103-bb4f-6052604868bd",
    "_rid": "t-E3AIxaencBAAAAAAAAAA==",
    "_self": "dbs/t-E3AA==/colls/t-E3AIxaenc=/docs/t-E3AIxaencBAAAAAAAAAA==/",
    "_etag": "\"00000000-0000-0000-9b50-fc769dc901d7\"",
    "_attachments": "attachments/",
    "_ts": 1630075016
}

Koleksi ini kemudian dapat diperbarui, sekali lagi dengan cara konvensional:

book.Quotes.Add("Pressing the emergency button lowered the rods again.");
book.Notes["48"] = "Chiesa d'Oro";

await context.SaveChangesAsync();

Keterbatasan:

Hanya kamus dengan kunci string yang akan didukung
Mengkueri konten koleksi primitif saat ini tidak didukung. Pilih #16926, #25700, dan #25701 jika fitur ini penting bagi Anda.

Terjemahan ke fungsi bawaan

Masalah GitHub: #16143.

Penyedia Azure Cosmos DB sekarang menerjemahkan lebih banyak metode Pustaka Kelas Dasar (BCL) ke fungsi bawaan Azure Cosmos DB. Tabel berikut menunjukkan terjemahan yang baru di EF Core 6.0.

Terjemahan string

Metode BCL	Fungsi bawaan	Catatan
`String.Length`	`LENGTH`
`String.ToLower`	`LOWER`
`String.TrimStart`	`LTRIM`
`String.TrimEnd`	`RTRIM`
`String.Trim`	`TRIM`
`String.ToUpper`	`UPPER`
`String.Substring`	`SUBSTRING`
`+` operator	`CONCAT`
`String.IndexOf`	`INDEX_OF`
`String.Replace`	`REPLACE`
`String.Equals`	`STRINGEQUAL`	Hanya panggilan yang tidak peka huruf besar/kecil

Terjemahan untuk LOWER, , RTRIMLTRIM, TRIM, UPPER, dan SUBSTRING dikontribusikan oleh @Marusyk. Terima kasih banyak!

Misalnya:

var stringResults = await context.Triangles.Where(
        e => e.Name.Length > 4
             && e.Name.Trim().ToLower() != "obtuse"
             && e.Name.TrimStart().Substring(2, 2).Equals("uT", StringComparison.OrdinalIgnoreCase))
    .ToListAsync();

Yang diterjemahkan ke:

SELECT c
FROM root c
WHERE ((c["Discriminator"] = "Triangle") AND (((LENGTH(c["Name"]) > 4) AND (LOWER(TRIM(c["Name"])) != "obtuse")) AND STRINGEQUALS(SUBSTRING(LTRIM(c["Name"]), 2, 2), "uT", true)))

Terjemahan matematika

Metode BCL	Fungsi bawaan
`Math.Abs` atau `MathF.Abs`	`ABS`
`Math.Acos` atau `MathF.Acos`	`ACOS`
`Math.Asin` atau `MathF.Asin`	`ASIN`
`Math.Atan` atau `MathF.Atan`	`ATAN`
`Math.Atan2` atau `MathF.Atan2`	`ATN2`
`Math.Ceiling` atau `MathF.Ceiling`	`CEILING`
`Math.Cos` atau `MathF.Cos`	`COS`
`Math.Exp` atau `MathF.Exp`	`EXP`
`Math.Floor` atau `MathF.Floor`	`FLOOR`
`Math.Log` atau `MathF.Log`	`LOG`
`Math.Log10` atau `MathF.Log10`	`LOG10`
`Math.Pow` atau `MathF.Pow`	`POWER`
`Math.Round` atau `MathF.Round`	`ROUND`
`Math.Sign` atau `MathF.Sign`	`SIGN`
`Math.Sin` atau `MathF.Sin`	`SIN`
`Math.Sqrt` atau `MathF.Sqrt`	`SQRT`
`Math.Tan` atau `MathF.Tan`	`TAN`
`Math.Truncate` atau `MathF.Truncate`	`TRUNC`
`DbFunctions.Random`	`RAND`

Terjemahan ini dikontribusikan oleh @Marusyk. Terima kasih banyak!

Misalnya:

var hypotenuse = 42.42;
var mathResults = await context.Triangles.Where(
        e => (Math.Round(e.Angle1) == 90.0
              || Math.Round(e.Angle2) == 90.0)
             && (hypotenuse * Math.Sin(e.Angle1) > 30.0
                 || hypotenuse * Math.Cos(e.Angle2) > 30.0))
    .ToListAsync();

Yang diterjemahkan ke:

SELECT c
FROM root c
WHERE ((c["Discriminator"] = "Triangle") AND (((ROUND(c["Angle1"]) = 90.0) OR (ROUND(c["Angle2"]) = 90.0)) AND (((@__hypotenuse_0 * SIN(c["Angle1"])) > 30.0) OR ((@__hypotenuse_0 * COS(c["Angle2"])) > 30.0))))

Terjemahan DateTime

Metode BCL	Fungsi bawaan
`DateTime.UtcNow`	`GetCurrentDateTime`

Terjemahan ini dikontribusikan oleh @Marusyk. Terima kasih banyak!

Misalnya:

var timeResults = await context.Triangles.Where(
        e => e.InsertedOn <= DateTime.UtcNow)
    .ToListAsync();

Yang diterjemahkan ke:

SELECT c
FROM root c
WHERE ((c["Discriminator"] = "Triangle") AND (c["InsertedOn"] <= GetCurrentDateTime()))

Kueri SQL mentah dengan FromSql

Masalah GitHub: #17311.

Terkadang perlu untuk menjalankan kueri SQL mentah alih-alih menggunakan LINQ. Ini sekarang didukung dengan penyedia Azure Cosmos DB melalui penggunaan FromSql metode . Ini bekerja dengan cara yang sama seperti yang selalu dilakukan dengan penyedia relasional. Contohnya:

var maxAngle = 60;
var results = await context.Triangles.FromSqlRaw(
        @"SELECT * FROM root c WHERE c[""Angle1""] <= {0} OR c[""Angle2""] <= {0}", maxAngle)
    .ToListAsync();

Yang dijalankan sebagai:

SELECT c
FROM (
    SELECT * FROM root c WHERE c["Angle1"] <= @p0 OR c["Angle2"] <= @p0
) c

Kueri yang berbeda

Masalah GitHub: #16144.

Kueri sederhana yang menggunakan Distinct sekarang diterjemahkan. Contohnya:

var distinctResults = await context.Triangles
    .Select(e => e.Angle1).OrderBy(e => e).Distinct()
    .ToListAsync();

Yang diterjemahkan ke:

SELECT DISTINCT c["Angle1"]
FROM root c
WHERE (c["Discriminator"] = "Triangle")
ORDER BY c["Angle1"]

Diagnostik

Masalah GitHub: #17298.

Penyedia Azure Cosmos DB sekarang mencatat lebih banyak informasi diagnostik, termasuk peristiwa untuk menyisipkan, mengkueri, memperbarui, dan menghapus data dari database. Unit permintaan (RU) disertakan dalam peristiwa ini kapan pun sesuai.

Catatan

Log menunjukkan penggunaan EnableSensitiveDataLogging() di sini sehingga nilai ID ditampilkan.

Menyisipkan item ke dalam database Azure Cosmos DB menghasilkan peristiwa tersebut CosmosEventId.ExecutedCreateItem . Misalnya, kode ini:

var triangle = new Triangle
{
    Name = "Impossible",
    PartitionKey = "TrianglesPartition",
    Angle1 = 90,
    Angle2 = 90,
    InsertedOn = DateTime.UtcNow
};
context.Add(triangle);
await context.SaveChangesAsync();