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

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

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

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

Примечание

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

В следующем примере настройка Score свойства с точностью 14 и масштабом 2 приведет к созданию столбца типа decimal(14,2) на SQL Server, а настройка LastUpdated свойства на точность 3 приведет к созданию столбца типа 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; }
}

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

Юникод

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

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

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

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

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

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

Соглашения

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

В C# 8 появилась новая функция, называемая ссылочными типами, допускающими значение NULL (NRT), которая позволяет добавлять аннотированные типы, указывая, допустимо ли для них содержать значение NULL. Эта функция включена по умолчанию в новых шаблонах проектов, но остается отключенной в существующих проектах, если она не была явно включена. Ссылочные типы, допускаемые значение 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, так как он передает допустимость значений NULL, выраженную в коде C#, в модель EF Core и в базу данных, а также устраняет использование API Fluent или заметок к данным, чтобы дважды выразить одну и ту же концепцию.

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечания к столбцу

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

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

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

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

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

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

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