Właściwości jednostki

Każdy typ jednostki w modelu ma zestaw właściwości, które program EF Core odczytuje i zapisuje z bazy danych. Jeśli używasz relacyjnej bazy danych, właściwości jednostki są mapowane na kolumny tabeli.

Uwzględnione i wykluczone właściwości

Zgodnie z konwencją wszystkie właściwości publiczne z elementem getter i modułem ustawiania zostaną uwzględnione w modelu.

Określone właściwości można wykluczyć w następujący sposób:

danych

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

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

Fluent API

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

Nazwy kolumn

Zgodnie z konwencją podczas korzystania z relacyjnej bazy danych właściwości jednostki są mapowane na kolumny tabeli o takiej samej nazwie jak właściwość.

Jeśli wolisz skonfigurować kolumny o różnych nazwach, możesz to zrobić jako następujący fragment kodu:

danych

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

    public string Url { get; set; }
}

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

Typy danych kolumn

W przypadku korzystania z relacyjnej bazy danych dostawca bazy danych wybiera typ danych na podstawie typu .NET właściwości. Uwzględnia również inne metadane, takie jak skonfigurowana maksymalna długość, czy właściwość jest częścią klucza podstawowego itp.

Na przykład dostawca SQL Server mapuje właściwości DateTime na kolumny datetime2(7) oraz właściwości string na kolumny nvarchar(max) (lub na nvarchar(450) dla właściwości używanych jako klucz).

Możesz również skonfigurować kolumny, aby określić dokładny typ danych dla kolumny. Na przykład poniższy kod konfiguruje Url jako ciąg znaków inny niż Unicode o maksymalnej długości 200, a Rating jako dziesiętny z dokładnością 5 i skalą 2.

danych

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

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

Maksymalna długość

Skonfigurowanie maksymalnej długości zapewnia dostawcy bazy danych wskazówkę dotyczącą odpowiedniego typu danych kolumny do wyboru dla danej właściwości. Maksymalna długość dotyczy tylko typów danych tablicy, takich jak string i byte[].

Notatka

Program Entity Framework nie wykonuje żadnej weryfikacji maksymalnej długości przed przekazaniem danych do dostawcy. Do dostawcy usług lub magazynu danych należy zweryfikowanie jego odpowiedniości. Na przykład, gdy celem jest SQL Server, przekroczenie maksymalnej długości spowoduje wyjątek, ponieważ typ danych podstawowej kolumny nie pozwoli na przechowywanie danych o nadmiarowej długości.

W poniższym przykładzie skonfigurowanie maksymalnej długości 500 spowoduje utworzenie kolumny typu nvarchar(500) w programie SQL Server:

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

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

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

Precyzja i skala

Niektóre typy danych relacyjnych obsługują aspekty dokładności i skalowania; określają, jakie wartości można przechowywać, oraz ilość miejsca potrzebnego do magazynowania w kolumnie. Obsługa precyzji i skalowania przez typy danych zależy od bazy danych, ale w większości baz danych typy decimal i DateTime obsługują te aspekty. W przypadku właściwości decimal precyzja definiuje maksymalną liczbę cyfr potrzebnych do wyrażenia dowolnej wartości, która będzie zawierać kolumna, a skala definiuje maksymalną wymaganą liczbę miejsc dziesiętnych. W przypadku właściwości DateTime precyzja definiuje maksymalną liczbę cyfr potrzebnych do wyrażenia ułamków sekund, a skalowanie nie jest używane.

Notatka

Program Entity Framework nie wykonuje żadnej walidacji dokładności ani skali przed przekazaniem danych do dostawcy. To do dostawcy lub magazynu danych należy odpowiednie sprawdzenie poprawności. Na przykład w przypadku określania wartości docelowej dla programu SQL Server kolumna typu danych datetime nie zezwala na ustawienie dokładności, natomiast datetime2 może mieć precyzję z zakresu od 0 do 7 włącznie.

W poniższym przykładzie skonfigurowanie właściwości Score o precyzji 14 i skalowaniu 2 spowoduje utworzenie kolumny typu decimal(14,2) w programie SQL Server i skonfigurowanie właściwości LastUpdated z dokładnością 3 spowoduje kolumnę typu datetime2(3):

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

Skalowanie nigdy nie jest definiowane bez uprzedniego zdefiniowania precyzji, dlatego adnotacja danych do definiowania skali jest [Precision(precision, scale)].

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

Skalowanie nigdy nie jest definiowane bez uprzedniego zdefiniowania precyzji, więc Fluent API do definiowania skali to HasPrecision(precision, scale).

Unicode

W niektórych relacyjnych bazach danych istnieją różne typy reprezentujące dane tekstowe Unicode i inne niż Unicode. Na przykład w programie SQL Server nvarchar(x) służy do reprezentowania danych Unicode w formacie UTF-16, podczas gdy varchar(x) służy do reprezentowania danych innych niż Unicode (ale zobacz uwagi dotyczące obsługi protokołu UTF-8 programu SQL Server). W przypadku baz danych, które nie obsługują tej koncepcji, skonfigurowanie tej koncepcji nie ma żadnego wpływu.

Właściwości tekstu są domyślnie konfigurowane jako Unicode. Możesz skonfigurować kolumnę jako inną niż Unicode w następujący sposób:

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

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

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

Wymagane i opcjonalne właściwości

Właściwość jest uważana za opcjonalną, jeśli jest prawidłowa, aby zawierała null. Jeśli null nie jest prawidłową wartością, która ma zostać przypisana do właściwości, jest uważana za wymaganą właściwość. Podczas mapowania do schematu relacyjnej bazy danych wymagane właściwości są tworzone jako kolumny nieakceptujące wartości null, a opcjonalne właściwości są tworzone jako kolumny akceptujące wartości null.

Konwencje

Zgodnie z konwencją właściwość, której typ platformy .NET może zawierać wartość null, zostanie skonfigurowana jako opcjonalna, natomiast właściwości, których typ platformy .NET nie może zawierać wartości null, zostaną skonfigurowane zgodnie z wymaganiami. Na przykład wszystkie właściwości z typami wartości .NET (int, decimal, boolitp.) są konfigurowane zgodnie z wymaganiami, a wszystkie właściwości z typami wartości null .NET (int?, decimal?, bool?itp.) są konfigurowane jako opcjonalne.

W języku C# 8 wprowadzono nową funkcję o nazwie typy odwołań dopuszczających wartość null (NRT), która umożliwia dodawanie adnotacji do typów odwołań, wskazujących, czy mogą one zawierać wartość null, czy nie. Ta funkcja jest domyślnie włączona w nowych szablonach projektów, ale pozostaje wyłączona w istniejących projektach, chyba że jawnie została wybrana. Typy referencyjne dopuszczające wartości null wpływają na działanie EF Core w następujący sposób:

• Jeśli typy odwołań dopuszczające wartość null są wyłączone, wszystkie właściwości z typami referencyjnymi platformy .NET są konfigurowane jako opcjonalne zgodnie z konwencją (na przykład string).
• Jeśli typy referencyjne z dopuszczeniem wartości null są włączone, właściwości zostaną skonfigurowane na podstawie nullowalności w C# ich typu .NET: string? zostanie skonfigurowana jako opcjonalna, ale string zostanie skonfigurowana jako wymagana.

W poniższym przykładzie przedstawiono typ jednostki z wymaganymi i opcjonalnymi właściwościami, z funkcją odwołania nullable wyłączoną i włączoną.

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

z

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

Używanie typów referencyjnych dopuszczających wartości null jest zalecane, ponieważ propaguje nullowalność wyrażoną w kodzie C# do modelu i bazy danych EF Core, eliminując konieczność dwukrotnego wyrażania tego samego pojęcia za pomocą interfejsu Fluent API lub adnotacji danych.

Notatka

Zachowaj ostrożność podczas włączania typów odwołań dopuszczających wartość null w istniejącym projekcie: właściwości typu odwołania, które zostały wcześniej skonfigurowane jako opcjonalne, będą teraz konfigurowane zgodnie z wymaganiami, chyba że są jawnie oznaczone jako dopuszczające wartość null. Podczas zarządzania schematem relacyjnej bazy danych może to spowodować wygenerowanie migracji, które zmieniają wartość null kolumny bazy danych.

Aby uzyskać więcej informacji na temat typów odwołań dopuszczanych do wartości null i sposobu ich używania z programem EF Core, zobacz dedykowaną stronę dokumentacji dla tej funkcji.

Jawna konfiguracja

Właściwość, która byłaby opcjonalna zgodnie z konwencją, może być wymagana w następujący sposób:

danych

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

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

API typu Fluent

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

Porównania kolumn

Sortowanie można zdefiniować w kolumnach tekstowych, określając sposób ich porównywania i porządkowania. Na przykład poniższy fragment kodu konfiguruje kolumnę w SQL Server na niewrażliwość na wielkość liter.

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

Jeśli wszystkie kolumny w bazie danych muszą używać określonego sortowania, zdefiniuj sortowanie na poziomie bazy danych.

Ogólne informacje o obsłudze sortowania w EF Core można znaleźć na stronie dokumentacji sortowania .

Komentarze kolumn

Możesz ustawić dowolny komentarz tekstowy ustawiony w kolumnie bazy danych, co umożliwia dokumentowanie schematu w bazie danych:

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

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

Fluent API

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

Kolejność kolumn

Domyślnie podczas tworzenia tabeli z Migrations, program EF Core zamawia najpierw kolumny klucza podstawowego, a następnie właściwości typu jednostki i typów należących do nich, a na koniec właściwości z typów bazowych. Można jednak określić inną kolejność kolumn:

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

Interfejs API Fluent może być używany do nadpisywania kolejności ustalanej przez atrybuty, w tym rozwiązywania konfliktów, gdy atrybuty na różnych właściwościach określają ten sam numer kolejności.

Fluent API

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

Należy pamiętać, że w ogólnym przypadku większość baz danych obsługuje tylko porządkowanie kolumn podczas tworzenia tabeli. Oznacza to, że atrybut order kolumny nie może być używany do ponownego porządkownia kolumn w istniejącej tabeli.