Свойства сущности

Статья
09/12/2023

Каждый тип сущности в модели имеет набор свойств, которые EF Core считывает и записывает из базы данных. Если вы используете реляционную базу данных, свойства сущности сопоставляют с столбцами таблицы.

Включенные и исключенные свойства

По соглашению все общедоступные свойства с методом получения и методом задания будут включены в модель.

Конкретные свойства можно исключить следующим образом:

Заметки к данным
Fluent API

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

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

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

Имена столбцов

По соглашению при использовании реляционной базы данных свойства сущности сопоставляются со столбцами таблицы с тем же именем, что и свойство.

Если вы предпочитаете настроить столбцы с разными именами, это можно сделать следующим фрагментом кода:

Заметки к данным
Fluent API

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

Типы данных столбцов

При использовании реляционной базы данных поставщик базы данных выбирает тип данных на основе типа .NET свойства. Кроме того, он учитывает другие метаданные, например настроенную максимальную длину, является ли свойство частью первичного ключа и т. д.

Например, SQL Server сопоставляет DateTime свойства datetime2(7) со столбцами и string свойствами nvarchar(max) столбцов (или nvarchar(450) для свойств, используемых в качестве ключа).

Вы также можете настроить столбцы, чтобы указать точный тип данных для столбца. Например, следующий код настраивается Url в виде строки, отличной от юникода, с максимальной длиной 200 и Rating десятичной с точностью 5 и масштабированием 2:

Заметки к данным
Fluent API

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

Максимальная длина

Настройка максимальной длины предоставляет указание поставщику базы данных о соответствующем типе данных столбца для выбора заданного свойства. Максимальная длина применяется только к типам данных массива, таким как string и byte[].

Примечание.

Entity Framework не выполняет проверку максимальной длины перед передачей данных поставщику. Он подходит поставщику или хранилищу данных для проверки соответствия требованиям. Например, при целевом использовании SQL Server превышение максимальной длины приведет к исключению, так как тип данных базового столбца не позволит хранить лишние данные.

В следующем примере настройка максимальной длины 500 приведет к созданию столбца типа nvarchar(500) в SQL Server:

Заметки к данным
Fluent API

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

Точность и масштабирование

Некоторые реляционные типы данных поддерживают аспекты точности и масштабирования; они определяют, какие значения можно хранить, и сколько хранилища требуется для столбца. Какие типы данных поддерживают точность и масштабирование, зависят от базы данных, но в большинстве баз данных decimal и DateTime типов поддерживают эти аспекты. Для decimal свойств точность определяет максимальное число цифр, необходимых для выражения любого значения столбца, и масштабирование определяет максимальное количество необходимых десятичных разрядов. Для DateTime свойств точность определяет максимальное количество цифр, необходимых для выражения дробей секунд, и масштабирование не используется.

Примечание.

Entity Framework не выполняет проверку точности или масштабирования перед передачей данных поставщику. Он подходит поставщику или хранилищу данных для проверки соответствующим образом. Например, при целевом объекте SQL Server столбец типа datetime данных не позволяет задать точность, в то время как datetime2 одна может иметь точность в диапазоне от 0 до 7 включительно.

В следующем примере настройка Score свойства с точностью 14 и масштабированием 2 приведет к созданию столбца типа decimal(14,2) в SQL Server и настройке LastUpdated свойства с точностью 3 приведет к тому, что столбец типа datetime2(3):

Заметки к данным
Fluent API

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

Масштабирование никогда не определяется без первой точности, поэтому заметка к данным для определения шкалы .[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);
}

Масштабирование никогда не определяется без первого определения точности, поэтому API Fluent для определения шкалы является HasPrecision(precision, scale).

Unicode

В некоторых реляционных базах данных различные типы существуют для представления текстовых данных Юникода и других типов. Например, в SQL Server nvarchar(x) используется для представления данных Юникода в UTF-16, а varchar(x) используется для представления данных, отличных от Юникода (но см. заметки о поддержке UTF-8 SQL Server). Для баз данных, которые не поддерживают эту концепцию, настройка этого не влияет.

Свойства текста настраиваются как Юникод по умолчанию. Вы можете настроить столбец как не юникод следующим образом:

Заметки к данным
Fluent API

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

Обязательные и необязательные свойства

Свойство считается необязательным, если он является допустимым для него null. Если null свойству не назначено допустимое значение, то оно считается обязательным. При сопоставлении с схемой реляционной базы данных необходимые свойства создаются в виде ненулевого столбца, а необязательные свойства создаются в качестве столбцов, допускающих значение NULL.

Соглашения

По соглашению свойство, тип .NET которого может содержать null, будет настроено как необязательное, в то время как свойства, тип .NET которых не может содержать null, будет настроен в соответствии с обязательным требованием. Например, все свойства с типами значений .NET (, decimal, boolи т. д.) настраиваются как обязательные, а все свойства с типамиint? значений .NET (int, decimal?, bool?и т. д.) настраиваются как необязательные.

C# 8 представил новую функцию, называемую ссылочными типами, допускающими значение NULL (NRT), что позволяет типы ссылок быть аннотированы, указывая, является ли он допустимым для них, чтобы содержать значение NULL или нет. Эта функция включена по умолчанию в новых шаблонах проектов, но остается отключенной в существующих проектах, если явно не будет разрешено. Типы ссылок, допускающие значение NULL, влияют на поведение EF Core следующим образом:

Если ссылочные типы, допускающие значение NULL, отключены, все свойства с ссылочными типами .NET настраиваются как необязательные по соглашению (например, string).
Если включены ссылочные типы, допускающие значение NULL, свойства будут настроены на основе nullability C# для типа .NET: string? будут настроены как необязательные, но string будут настроены по мере необходимости.

В следующем примере показан тип сущности с обязательными и необязательными свойствами с отключенной и включенной функцией ссылки, допускающая значение NULL:

Без NRT (по умолчанию)
С 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
}

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

Использование ссылочных типов, допускающих значение NULL, рекомендуется, так как оно передает значение NULL, выраженное в коде C#, в модель EF Core и в базу данных, а также устраняет использование API Fluent или примечаний к данным для выражения одной и той же концепции дважды.

Примечание.

Соблюдайте осторожность при включении ссылочных типов, допускающих значение NULL в существующем проекте: свойства ссылочного типа, которые ранее были настроены как необязательные, теперь будут настроены в соответствии с обязательными требованиями, если они явно не помечены как значения NULL. При управлении схемой реляционной базы данных это может привести к созданию миграций, которые изменяют допустимость null столбца базы данных.

Дополнительные сведения о типах ссылок, допускающих значение NULL, и их использовании с EF Core, см. на странице выделенной документации для этой функции.

Явная конфигурация

Свойство, которое будет необязательным по соглашению, можно настроить следующим образом:

Заметки к данным
Fluent API

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

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

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

Параметры сортировки столбцов

Параметры сортировки можно определить в текстовых столбцах, определяя, как они сравниваются и упорядочены. Например, следующий фрагмент кода настраивает столбец SQL Server для учета регистра:

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

Если все столбцы в базе данных должны использовать определенную сортировку, определите параметры сортировки на уровне базы данных.

Общие сведения о поддержке параметров сортировки EF Core см. на странице документации по сортировке.

Комментарии к столбцам

Можно задать произвольный текстовый комментарий, который устанавливается в столбце базы данных, что позволяет документировать схему в базе данных:

Заметки к данным
Fluent API

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

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

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

Порядок столбцов

По умолчанию при создании таблицы с помощью migrations ef Core сначала упорядочивает столбцы первичного ключа, а затем свойства типа сущности и собственных типов, а также свойства из базовых типов. Однако можно указать другой порядок столбцов:

Заметки к данным
Fluent API

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 Fluent можно использовать для переопределения упорядочения с атрибутами, включая разрешение любых конфликтов, когда атрибуты в разных свойствах указывают один и тот же номер заказа.

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

Обратите внимание, что в общем случае большинство баз данных поддерживает упорядочение столбцов только при создании таблицы. Это означает, что атрибут порядка столбцов нельзя использовать для переупорядочения столбцов в существующей таблице.

Поделиться через

Свойства сущности

Включенные и исключенные свойства

Имена столбцов

Типы данных столбцов

Максимальная длина

Точность и масштабирование

Unicode

Обязательные и необязательные свойства

Соглашения

Явная конфигурация

Параметры сортировки столбцов

Комментарии к столбцам

Порядок столбцов

Дополнительные ресурсы