Управление миграциями

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

Добавить миграцию

После изменения вашей модели, можно добавить миграцию для этого изменения.

dotnet ef migrations add AddBlogCreatedTimestamp

Add-Migration AddBlogCreatedTimestamp

Имя миграции можно использовать как сообщение коммита в системе управления версиями. Например, можно выбрать имя, например, AddBlogCreatedTimestamp, если изменение является новым свойством CreatedTimestamp в сущности Blog.

В ваш проект в каталоге миграции добавляются три файла.

• XXXXXXXXXXXXXX_AddBlogCreatedTimestamp.cs- Основной файл миграции. Содержит операции, необходимые для применения миграции (в Up) и для возврата (в Down).
• XXXXXXXXXXXXXX_AddBlogCreatedTimestamp.Designer.cs--Файл метаданных миграции. Содержит сведения, используемые EF.
• MyContextModelSnapshot.cs--Моментальный снимок вашей текущей модели. Используется для определения того, что изменилось при добавлении следующей миграции.

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

Пространства имен

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

dotnet ef migrations add InitialCreate --output-dir Your/Directory

Add-Migration InitialCreate -OutputDir Your\Directory

Настройка кода миграции

Хотя EF Core обычно создает точные миграции, следует всегда просматривать код и убедиться, что он соответствует требуемому изменению; В некоторых случаях это даже необходимо сделать.

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

Один из ярких примеров, требующих настройки миграции, — это переименование свойства. Например, если переименовать свойство из Name в FullName, EF Core создаст следующую миграцию:

migrationBuilder.DropColumn(
    name: "Name",
    table: "Customers");

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customers",
    nullable: true);

EF Core обычно не может знать, когда намерение удалить столбец и создать новый (два отдельных изменения), а также когда столбец следует переименовать. Если вышеуказанная миграция будет применена as-is, все имена ваших клиентов будут утеряны. Чтобы переименовать столбец, замените сгенерированную выше миграцию на следующую:

migrationBuilder.RenameColumn(
    name: "Name",
    table: "Customers",
    newName: "FullName");

Добавление необработанного SQL

Хотя переименование столбца можно выполнить с помощью встроенного API, в большинстве случаев это невозможно. Например, мы можем заменить существующие FirstName и LastName свойства одним новым свойством FullName. Миграция, созданная EF Core, будет следующей:

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customer",
    nullable: true);

Как и раньше, это приведет к нежелательной потере данных. Чтобы перенести данные из старых столбцов, мы реорганизуем процесс миграции и вводим необработанный SQL-операцию следующим образом:

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customer",
    nullable: true);

migrationBuilder.Sql(
@"
    UPDATE Customer
    SET FullName = FirstName + ' ' + LastName;
");

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

Произвольные изменения с помощью необработанного SQL

Необработанный SQL также можно использовать для управления объектами базы данных, о которых EF Core не знает. Для этого добавьте миграцию, не изменив модель; Будет создана пустая миграция, которую можно заполнить необработанными операциями SQL.

Например, следующая миграция создает хранимую процедуру SQL Server:

migrationBuilder.Sql(
@"
    EXEC ('CREATE PROCEDURE getFullName
        @LastName nvarchar(50),
        @FirstName nvarchar(50)
    AS
        RETURN @LastName + @FirstName;')");

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

• Хранимые процедуры
• полнотекстовый поиск
• Функции
• Триггеры
• Представления

В большинстве случаев EF Core автоматически упаковывает каждую миграцию в отдельную транзакцию при применении миграций. К сожалению, некоторые операции миграции не могут выполняться в рамках транзакции в некоторых базах данных; в этих случаях вы можете отказаться от транзакции, передав suppressTransaction: true в migrationBuilder.Sql.

Удалить миграцию

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

dotnet ef migrations remove

Remove-Migration

После удаления миграции можно внести дополнительные изменения в модель и снова добавить ее.

Перечисление миграций

Вы можете перечислить все существующие миграции следующим образом:

dotnet ef migrations list

Get-Migration

Проверка ожидающих изменений модели

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

dotnet ef migrations has-pending-model-changes

Вы также можете выполнить эту проверку программным способом с помощью context.Database.HasPendingModelChanges(). Это можно использовать для создания модульного теста, который завершится сбоем, если вы забудете добавить миграцию.

Сброс всех миграций

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

Можно также сбросить все миграции и создать одну, не теряя данные. Иногда это называется "скваширование", и включает в себя некоторые ручной работы:

1. Создайте резервную копию базы данных, если что-то не так.
2. В базе данных удалите все строки из таблицы журнала миграций (например, DELETE FROM [__EFMigrationsHistory] в SQL Server).
3. Удалите папку миграции.
4. Создайте новую миграцию и создайте для него скрипт SQL (dotnet ef migrations script).
5. Вставьте одну строку в журнал миграций, чтобы записать, что первая миграция уже применена, так как таблицы уже есть. Вставка SQL является последней операцией в скрипте SQL, созданном выше, и напоминает следующее (не забудьте обновить значения):

INSERT INTO [__EFMigrationsHistory] ([MIGRATIONID], [PRODUCTVERSION])
VALUES (N'<full_migration_timestamp_and_name>', N'<EF_version>');

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

• справочник по инструментам Entity Framework Core — интерфейс командной строки .NET Core: включает команды для обновления, сброса, добавления, удаления и т. д.
• Справочник по инструментам Entity Framework Core — консоль диспетчера пакетов в Visual Studio: включает команды для обновления, удаления, добавления, перемещения и т. д.