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

Статья
01/15/2025

Каждый тип сущности в модели имеет набор свойств, которые 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);
}

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

Юникод

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

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

аннотации данных
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 (int, decimal, boolи т. д.) настроены как обязательные, а все свойства с допускающими null типами значений .NET (int?, decimal?, bool?и т. д.) настроены как необязательные.

В C# 8 появилась новая функция, называемая nullable ссылочные типы (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, см. на посвящённой этой функции странице документации.

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

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

аннотации данных
Флюент 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");
}

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

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

аннотации данных
Флюент 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; }
}

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

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

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

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

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

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

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

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

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

Юникод

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

Конвенции

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

Сопоставления столбцов

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

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

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