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

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

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

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

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

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

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

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

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

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

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

    public string Url { get; set; }
}

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Начиная с Ефкоре 5,0 можно использовать API Fluent, чтобы настроить точность и масштаб. Он сообщает поставщику базы данных, какой объем хранилища требуется для данного столбца. Он применяется только к типам данных, где поставщик допускает точность и масштабирование в зависимости от того, как правило decimal , и DateTime .

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

Примечание

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

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

В настоящее время невозможно настроить точность и масштаб с помощью заметок к данным.

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

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

Соглашения

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

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

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

В следующем примере показан тип сущности с обязательными и необязательными свойствами с отключенной ссылкой, допускающей значение null (по умолчанию) и включенной.

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

Примечание

Эта возможность появилась в EF Core 5.0.

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

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

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

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

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

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

Примечание

Установка комментариев с помощью заметок к данным была представлена в EF Core 5,0.

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

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