Sifat Entitas

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

Properti yang disertakan dan dikecualikan

Konvensi menyatakan bahwa 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");
}

Jenis 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, penyedia SQL Server memetakan properti DateTime ke kolom datetime2(7), dan string properti ke kolom nvarchar(max) (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 maksimum 200 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[].

Nota

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 yang mendukung presisi dan skala tergantung pada database, tetapi dalam sebagian besar database, jenis decimal dan DateTime mendukung faset ini. Untuk properti decimal, 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 properti DateTime, presisi menentukan jumlah maksimum digit yang diperlukan untuk mengekspresikan pecahan detik, dan skala tidak digunakan.

Nota

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

Dalam contoh berikut, mengonfigurasi properti Score agar memiliki presisi 14 dan skala 2 akan menyebabkan kolom jenis decimal(14,2) dibuat di SQL Server, dan mengonfigurasi properti LastUpdated 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, jadi Anotasi Data untuk mendefinisikan 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 Fluent API 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 tentang 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 bersifat wajib dan opsional

Properti dianggap opsional jika dinyatakan valid bahwa ia dapat 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, decimal, bool, dll.) dikonfigurasi sesuai kebutuhan, dan semua properti dengan jenis nilai .NET nullable (int?, decimal?, bool?, dll.) dikonfigurasi sebagai opsional.

Jenis referensi nullable C# (NRT) memungkinkan jenis referensi diberi anotasi, yang menunjukkan apakah jenis tersebut valid 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 tipe referensi yang dapat di-null diaktifkan, properti akan dikonfigurasi berdasarkan kemampuan null C# dari tipe .NET-nya: string? akan dikonfigurasi sebagai opsional, tetapi string akan dikonfigurasi sebagai diperlukan.

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

Dengan

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;
    }
}

Tanpa NRT

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
}

Disarankan menggunakan jenis referensi nullable karena mengalihkan sifat nullable yang diekspresikan dalam kode C# ke model EF Core dan database, serta menghilangkan kebutuhan penggunaan Fluent API atau Anotasi Data untuk mengekspresikan konsep yang sama dua kali.

Nota

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. Pada saat mengelola skema database relasional, ini dapat menimbulkan migrasi yang mengubah kemampuan kolom database untuk menerima nilai null.

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();
}

Kolasi 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 Migrations, 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 mengesampingkan urutan yang dibuat dengan atribut, termasuk menyelesaikan konflik apa pun ketika atribut pada properti yang berbeda menentukan nomor urutan 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.