Properti Entitas

Setiap jenis entitas dalam model Anda memiliki sekumpulan properti, yang akan dibaca dan ditulis EF Core dari database. Jika Anda menggunakan database relasional, properti entitas memetakan ke kolom tabel.

Properti yang disertakan dan dikecualikan

Menurut konvensi, semua properti publik dengan getter dan setter akan disertakan dalam model.

Properti tertentu dapat dikecualikan sebagai berikut:

Anotasi Data

public class Blog
{
    public int BlogId { get; set; }
    public string Url { get; set; }

    [NotMapped]
    public DateTime LoadedFromDatabase { get; set; }
}

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Ignore(b => b.LoadedFromDatabase);
}

Nama kolom

Menurut konvensi, saat menggunakan database relasional, properti entitas dipetakan ke kolom tabel yang memiliki nama yang sama dengan properti .

Jika Anda lebih suka mengonfigurasi kolom dengan nama yang berbeda, Anda bisa melakukannya sebagai cuplikan kode berikut:

Anotasi Data

public class Blog
{
    [Column("blog_id")]
    public int BlogId { get; set; }

    public string Url { get; set; }
}

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.BlogId)
        .HasColumnName("blog_id");
}

Tipe data kolom

Saat menggunakan database relasional, penyedia database memilih jenis data berdasarkan jenis .NET properti. Ini juga memperhitungkan metadata lain, seperti panjang maksimum yang dikonfigurasi, apakah properti adalah bagian dari kunci primer, dll.

Misalnya, SQL Server memetakan DateTime properti ke datetime2(7) kolom, dan string properti ke nvarchar(max) kolom (atau untuk nvarchar(450) properti yang digunakan sebagai kunci).

Anda juga dapat mengonfigurasi kolom untuk menentukan jenis data yang tepat untuk kolom. Misalnya, kode berikut mengonfigurasi Url sebagai string non-unicode dengan panjang 200 maksimum dan Rating sebagai desimal dengan presisi 5 dan skala 2:

Anotasi Data

public class Blog
{
    public int BlogId { get; set; }

    [Column(TypeName = "varchar(200)")]
    public string Url { get; set; }

    [Column(TypeName = "decimal(5, 2)")]
    public decimal Rating { get; set; }
}

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>(
        eb =>
        {
            eb.Property(b => b.Url).HasColumnType("varchar(200)");
            eb.Property(b => b.Rating).HasColumnType("decimal(5, 2)");
        });
}

Panjang maksimum

Mengonfigurasi panjang maksimum memberikan petunjuk kepada penyedia database tentang jenis data kolom yang sesuai untuk dipilih untuk properti tertentu. Panjang maksimum hanya berlaku untuk jenis data array, seperti string dan byte[].

Catatan

Kerangka Kerja Entitas tidak melakukan validasi panjang maksimum sebelum meneruskan data ke penyedia. Terserah penyedia atau penyimpanan data untuk memvalidasi jika sesuai. Misalnya, saat menargetkan SQL Server, melebihi panjang maksimum akan menghasilkan pengecualian karena jenis data kolom yang mendasar tidak akan memungkinkan data berlebih disimpan.

Dalam contoh berikut, mengonfigurasi panjang maksimum 500 akan menyebabkan kolom jenis nvarchar(500) dibuat di SQL Server:

Anotasi Data

public class Blog
{
    public int BlogId { get; set; }

    [MaxLength(500)]
    public string Url { get; set; }
}

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .HasMaxLength(500);
}

Presisi dan Skala

Beberapa jenis data relasional mendukung faset presisi dan skala; ini mengontrol nilai apa yang dapat disimpan, dan berapa banyak penyimpanan yang diperlukan untuk kolom. Jenis data mana yang mendukung presisi dan skala yang bergantung pada database, tetapi di sebagian besar database decimal dan DateTime jenis mendukung faset ini. Untuk decimal properti, presisi menentukan jumlah maksimum digit yang diperlukan untuk mengekspresikan nilai apa pun yang akan dimuat kolom, dan skala menentukan jumlah maksimum tempat desimal yang diperlukan. Untuk DateTime properti, presisi mendefinisikan jumlah maksimum digit yang diperlukan untuk mengekspresikan pecahan detik, dan skala tidak digunakan.

Catatan

Kerangka Kerja Entitas tidak melakukan validasi presisi atau skala sebelum meneruskan data ke penyedia. Terserah penyedia atau penyimpanan data untuk memvalidasi sebagaimana mewajarkan. Misalnya, saat menargetkan SQL Server, kolom jenis datetime data tidak memungkinkan presisi diatur, sedangkan datetime2 yang dapat memiliki presisi antara 0 dan 7 inklusif.

Dalam contoh berikut, mengonfigurasi Score properti untuk memiliki presisi 14 dan skala 2 akan menyebabkan kolom jenis decimal(14,2) dibuat di SQL Server, dan mengonfigurasi LastUpdated properti memiliki presisi 3 akan menyebabkan kolom jenis datetime2(3):

Anotasi Data

public class Blog
{
    public int BlogId { get; set; }
    [Precision(14, 2)]
    public decimal Score { get; set; }
    [Precision(3)]
    public DateTime LastUpdated { get; set; }
}

Skala tidak pernah didefinisikan tanpa terlebih dahulu menentukan presisi, sehingga Anotasi Data untuk menentukan skala adalah [Precision(precision, scale)].

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Score)
        .HasPrecision(14, 2);

    modelBuilder.Entity<Blog>()
        .Property(b => b.LastUpdated)
        .HasPrecision(3);
}

Skala tidak pernah didefinisikan tanpa terlebih dahulu menentukan presisi, sehingga API Fasih untuk menentukan skala adalah HasPrecision(precision, scale).

Unicode

Dalam beberapa database relasional, jenis yang berbeda ada untuk mewakili data teks Unicode dan non-Unicode. Misalnya, di SQL Server, nvarchar(x) digunakan untuk mewakili data Unicode di UTF-16, sementara varchar(x) digunakan untuk mewakili data non-Unicode (tetapi lihat catatan pada dukungan SQL Server UTF-8). Untuk database yang tidak mendukung konsep ini, mengonfigurasi ini tidak berpengaruh.

Properti teks dikonfigurasi sebagai Unicode secara default. Anda dapat mengonfigurasi kolom sebagai non-Unicode sebagai berikut:

Anotasi Data

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }

    [Unicode(false)]
    [MaxLength(22)]
    public string Isbn { get; set; }
}

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Book>()
        .Property(b => b.Isbn)
        .IsUnicode(false);
}

Properti yang diperlukan dan opsional

Properti dianggap opsional jika valid untuk berisi null. Jika null bukan nilai yang valid untuk ditetapkan ke properti maka dianggap sebagai properti yang diperlukan. Saat memetakan ke skema database relasional, properti yang diperlukan dibuat sebagai kolom yang tidak dapat diubah ke null, dan properti opsional dibuat sebagai kolom yang dapat diubah ke null.

Konvensi

Menurut konvensi, properti yang jenis .NET-nya dapat berisi null akan dikonfigurasi sebagai opsional, sedangkan properti yang jenis .NET-nya tidak boleh berisi null akan dikonfigurasi sesuai kebutuhan. Misalnya, semua properti dengan jenis nilai .NET (int, , , booldll.) dikonfigurasi sesuai kebutuhan, dan semua properti dengan jenis nilai .NET nullable (int?, decimal?, bool?, dll.) dikonfigurasi decimalsebagai opsional.

C# 8 memperkenalkan fitur baru yang disebut nullable reference type (NRT), yang memungkinkan jenis referensi untuk diannotasi, menunjukkan apakah itu valid bagi mereka untuk berisi null atau tidak. Fitur ini diaktifkan secara default dalam templat proyek baru, tetapi tetap dinonaktifkan dalam proyek yang ada kecuali diikutsertakan secara eksplisit. Jenis referensi nullable memengaruhi perilaku EF Core dengan cara berikut:

• Jika jenis referensi nullable dinonaktifkan, semua properti dengan jenis referensi .NET dikonfigurasi sebagai opsional menurut konvensi (misalnya, string).
• Jika jenis referensi nullable diaktifkan, properti akan dikonfigurasi berdasarkan nullability C# dari jenis .NET mereka: string? akan dikonfigurasi sebagai opsional, tetapi string akan dikonfigurasi sesuai kebutuhan.

Contoh berikut menunjukkan jenis entitas dengan properti yang diperlukan dan opsional, dengan fitur referensi nullable dinonaktifkan dan diaktifkan:

Tanpa NRT (default)

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

    [Required] // Data annotations needed to configure as required
    public string FirstName { get; set; }

    [Required] // Data annotations needed to configure as required
    public string LastName { get; set; }

    public string MiddleName { get; set; } // Optional by convention
}

Dengan NRT

public class Customer
{
    public int Id { get; set; }
    public string FirstName { get; set; } // Required by convention
    public string LastName { get; set; } // Required by convention
    public string? MiddleName { get; set; } // Optional by convention

    // Note the following use of constructor binding, which avoids compiled warnings
    // for uninitialized non-nullable properties.
    public Customer(string firstName, string lastName, string? middleName = null)
    {
        FirstName = firstName;
        LastName = lastName;
        MiddleName = middleName;
    }
}

Menggunakan jenis referensi nullable disarankan karena mengalirkan nullability yang dinyatakan dalam kode C# ke model EF Core dan ke database, dan mengaburkan penggunaan Fluent API atau Anotasi Data untuk mengekspresikan konsep yang sama dua kali.

Catatan

Berhati-hatilah saat mengaktifkan jenis referensi nullable pada proyek yang ada: properti jenis referensi yang sebelumnya dikonfigurasi sebagai opsional sekarang akan dikonfigurasi sesuai kebutuhan, kecuali jika secara eksplisit dianotasikan menjadi nullable. Saat mengelola skema database relasional, ini dapat menyebabkan migrasi dihasilkan yang mengubah nullability kolom database.

Untuk informasi selengkapnya tentang jenis referensi nullable dan cara menggunakannya dengan EF Core, lihat halaman dokumentasi khusus untuk fitur ini.

Konfigurasi eksplisit

Properti yang bersifat opsional menurut konvensi dapat dikonfigurasi agar diperlukan sebagai berikut:

Anotasi Data

public class Blog
{
    public int BlogId { get; set; }

    [Required]
    public string Url { get; set; }
}

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .IsRequired();
}

Kolatasi kolom

Kolase dapat ditentukan pada kolom teks, menentukan bagaimana mereka dibandingkan dan diurutkan. Misalnya, cuplikan kode berikut mengonfigurasi kolom SQL Server agar tidak peka huruf besar/kecil:

modelBuilder.Entity<Customer>().Property(c => c.Name)
    .UseCollation("SQL_Latin1_General_CP1_CI_AS");

Jika semua kolom dalam database perlu menggunakan kolatasi tertentu, tentukan kolatasi di tingkat database sebagai gantinya.

Informasi umum tentang dukungan EF Core untuk kolase dapat ditemukan di halaman dokumentasi kolase.

Komentar kolom

Anda bisa mengatur komentar teks arbitrer yang diatur pada kolom database, memungkinkan Anda mendokumentasikan skema Anda dalam database:

Anotasi Data

public class Blog
{
    public int BlogId { get; set; }

    [Comment("The URL of the blog")]
    public string Url { get; set; }
}

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .HasComment("The URL of the blog");
}

Urutan kolom

Secara default saat membuat tabel dengan Migrasi, EF Core mengurutkan kolom kunci utama terlebih dahulu, diikuti oleh properti jenis entitas dan jenis yang dimiliki, dan akhirnya properti dari jenis dasar. Namun, Anda dapat menentukan urutan kolom yang berbeda:

Anotasi Data

public class EntityBase
{
    [Column(Order = 0)]
    public int Id { get; set; }
}

public class PersonBase : EntityBase
{
    [Column(Order = 1)]
    public string FirstName { get; set; }

    [Column(Order = 2)]
    public string LastName { get; set; }
}

public class Employee : PersonBase
{
    public string Department { get; set; }
    public decimal AnnualSalary { get; set; }
}

API Fasih dapat digunakan untuk mengambil alih pemesanan yang dibuat dengan atribut, termasuk menyelesaikan konflik apa pun saat atribut pada properti yang berbeda menentukan nomor pesanan yang sama.

API Fasih

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Employee>(x =>
    {
        x.Property(b => b.Id)
            .HasColumnOrder(0);

        x.Property(b => b.FirstName)
            .HasColumnOrder(1);

        x.Property(b => b.LastName)
            .HasColumnOrder(2);
    });
}

Perhatikan bahwa, dalam kasus umum, sebagian besar database hanya mendukung pengurutan kolom saat tabel dibuat. Ini berarti bahwa atribut urutan kolom tidak dapat digunakan untuk mengurutkan ulang kolom dalam tabel yang sudah ada.