МиграцииMigrations

Модель данных в процессе разработки может измениться и перестанет соответствовать базе данных.A data model changes during development and gets out of sync with the database. Вы всегда можете удалить базу данных, и EF создаст для вас новую версию, в точности соответствующую модели, но такая процедура приводит к потере текущих данных.You can drop the database and let EF create a new one that matches the model, but this procedure results in the loss of data. Функция миграции в EF Core позволяет последовательно применять изменения схемы к базе данных, чтобы синхронизировать ее с моделью данных в приложении без потери существующих данных.The migrations feature in EF Core provides a way to incrementally update the database schema to keep it in sync with the application's data model while preserving existing data in the database.

Миграции включают средства командной строки и API-интерфейсы, которые помогают в решении следующих задач:Migrations includes command-line tools and APIs that help with the following tasks:

Совет

Если DbContext находится не в той же сборке, что и начальный проект, можно явным образом указать целевой и начальный проекты в средствах консоли диспетчера пакетов или в средствах .NET Core CLI.If the DbContext is in a different assembly than the startup project, you can explicitly specify the target and startup projects in either the Package Manager Console tools or the .NET Core CLI tools.

Установка инструментовInstall the tools

Установите средства командной строки.Install the command-line tools:

Создание миграцииCreate a migration

После того, как вы определите начальную модель, можно переходить к созданию базы данных.After you've defined your initial model, it's time to create the database. Чтобы добавить первоначальную миграцию, выполните следующую команду.To add an initial migration, run the following command.

dotnet ef migrations add InitialCreate

В каталог Migrations проекта добавляются три файла.Three files are added to your project under the Migrations directory:

  • XXXXXXXXXXXXXX_InitialCreate.cs — главный файл миграций.XXXXXXXXXXXXXX_InitialCreate.cs--The main migrations file. Содержит операции, необходимые для применения миграции (в Up()) и ее отмены (в Down()).Contains the operations necessary to apply the migration (in Up()) and to revert it (in Down()).
  • XXXXXXXXXXXXXX_InitialCreate.Designer.cs — файл метаданных миграций.XXXXXXXXXXXXXX_InitialCreate.Designer.cs--The migrations metadata file. Содержит сведения, используемые EF.Contains information used by EF.
  • MyContextModelSnapshot.cs — моментальный снимок текущей модели.MyContextModelSnapshot.cs--A snapshot of your current model. Используется для определения появившихся изменений при добавлении следующей миграции.Used to determine what changed when adding the next migration.

Метка времени в именах файлов позволяет расположить их в хронологическом порядке, чтобы вы могли отслеживать ход изменений.The timestamp in the filename helps keep them ordered chronologically so you can see the progression of changes.

Совет

Вы можете свободно перемещать файлы миграций и изменять их пространство имен.You are free to move Migrations files and change their namespace. Новые миграции создаются в виде элементов того же уровня, что и последняя миграция.New migrations are created as siblings of the last migration.

Обновление базы данныхUpdate the database

После этого примените миграцию к базе данных, чтобы создать схему.Next, apply the migration to the database to create the schema.

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

После внесения изменений в модель EF Core может нарушиться синхронизация схемы базы данных. Чтобы сделать ее актуальной, добавьте еще одну миграцию.After making changes to your EF Core model, the database schema might be out of sync. To bring it up to date, add another migration. Имя миграции можно использовать как сообщение фиксации в системе управления версиями.The migration name can be used like a commit message in a version control system. Например, вы можете выбрать имя AddProductReviews, если суть изменений заключается в создании нового класса сущностей для обзоров.For example, you might choose a name like AddProductReviews if the change is a new entity class for reviews.

dotnet ef migrations add AddProductReviews

После создания кода миграции проверьте, правильно ли он создан. Если потребуется, добавьте, удалите или измените любые операции для правильного применения изменений.Once the migration is scaffolded (code generated for it), review the code for accuracy and add, remove or modify any operations required to apply it correctly.

Например, миграция может содержать следующие операции.For example, a migration might contain the following operations:

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

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

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

Хотя эти операции обеспечивают совместимость схемы базы данных, они не сохраняют существующие имена клиентов.While these operations make the database schema compatible, they don't preserve the existing customer names. Чтобы улучшить миграцию, перепишите ее следующим образом.To make it better, rewrite it as follows.

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

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

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

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

Совет

Процесс создания новой миграции предупреждает, если операция может привести к потере данных (например, содержит удаление столбца).The migration scaffolding process warns when an operation might result in data loss (like dropping a column). Увидев это предупреждение, проверьте точность кода миграции с особой тщательностью.If you see that warning, be especially sure to review the migrations code for accuracy.

Примените миграцию к базе данных с помощью соответствующей команды.Apply the migration to the database using the appropriate command.

Пустые миграцииEmpty migrations

Иногда бывает удобно добавить миграцию, не внося изменения в модель.Sometimes it's useful to add a migration without making any model changes. В этом случае при добавлении новой миграции создаются файлы кода с пустыми классами.In this case, adding a new migration creates code files with empty classes. Вы можете настроить ее для выполнения операций, которые не связаны напрямую с моделью EF Core.You can customize this migration to perform operations that don't directly relate to the EF Core model. Ниже приведен ряд вещей, которыми вам может потребоваться управлять.Some things you might want to manage this way are:

  • Полнотекстовый поискFull-Text Search
  • ФункцииFunctions
  • Хранимые процедурыStored procedures
  • ТриггерыTriggers
  • ПредставленияViews

Удаление миграцииRemove a migration

Иногда, добавив миграцию, вы понимаем, что нужно внести дополнительные изменения в модель EF Core перед ее применением.Sometimes you add a migration and realize you need to make additional changes to your EF Core model before applying it. Для удаления последней миграции используйте приведенную ниже команду.To remove the last migration, use this command.

Удалив миграцию, вы можете внести в модель дополнительные изменения и снова добавить ее.After removing the migration, you can make the additional model changes and add it again.

Отмена миграцииRevert a migration

Если вы уже применили одну миграцию для базы данных или несколько и хотите отменить их, можно использовать ту же команду, что и для применения миграций, но указав имя миграции, к которой надо откатить изменения.If you already applied a migration (or several migrations) to the database but need to revert it, you can use the same command to apply migrations, but specify the name of the migration you want to roll back to.

dotnet ef database update LastGoodMigration

Создание скриптов SQLGenerate SQL scripts

При отладке миграций или их развертывании в рабочей базе данных бывает полезно создать скрипт SQL.When debugging your migrations or deploying them to a production database, it's useful to generate a SQL script. Такой скрипт можно дополнительно проверить на точность и настроить в соответствии с потребностями рабочей базы данных.The script can then be further reviewed for accuracy and tuned to fit the needs of a production database. Кроме того, его можно использовать в сочетании с технологией развертывания.The script can also be used in conjunction with a deployment technology. Базовая команда имеет следующий вид.The basic command is as follows.

Основное использованиеBasic Usage

dotnet ef migrations script

С from (в подразумеваемую миграцию)With From (to implied)

Будет создан скрипт SQL из этой миграции в последнюю миграцию.This will generate a SQL script from this migration to the latest migration.

dotnet ef migrations script 20190725054716_Add_new_tables

С from и toWith From and To

Будет создан скрипт SQL из миграции fromв указанную миграцию to.This will generate a SQL script from the from migration to the specified to migration.

dotnet ef migrations script 20190725054716_Add_new_tables 20190829031257_Add_audit_table

Для создания скрипта отката можно использовать значение from, более новое, чем to.You can use a from that is newer than the to in order to generate a rollback script. Обязательно учитывайте возможные сценарии потери данных.Please take note of potential data loss scenarios.

Для этой команды доступно несколько параметров.There are several options to this command.

Миграция from должна быть последней миграцией, применяемой к базе данных перед выполнением скрипта.The from migration should be the last migration applied to the database before running the script. Если не было применено ни одной миграции, укажите 0 (это значение по умолчанию).If no migrations have been applied, specify 0 (this is the default).

Миграция to является последней миграцией, применяемой к базе данных после выполнения скрипта.The to migration is the last migration that will be applied to the database after running the script. По умолчанию она является последней миграцией в проекте.This defaults to the last migration in your project.

При необходимости можно создать идемпотентный скрипт.An idempotent script can optionally be generated. Он применяет миграции только в том случае, если они еще не были применены к базе данных.This script only applies migrations if they haven't already been applied to the database. Это удобно, если точно неизвестно, какая последняя миграция была применена к базе данных, или вы развертываете несколько баз данных, каждая из которых может иметь отдельную миграцию.This is useful if you don't exactly know what the last migration applied to the database was or if you are deploying to multiple databases that may each be at a different migration.

Применение миграции во время выполненияApply migrations at runtime

Некоторым приложениям может потребоваться применить миграции во время выполнения — при запуске или первом выполнении.Some apps may want to apply migrations at runtime during startup or first run. Для этого можно использовать метод Migrate().Do this using the Migrate() method.

Этот метод основан на службе IMigrator, которую можно применять в более сложных сценариях.This method builds on top of the IMigrator service, which can be used for more advanced scenarios. Для доступа к нему используйте myDbContext.GetInfrastructure().GetService<IMigrator>().Use myDbContext.GetInfrastructure().GetService<IMigrator>() to access it.

myDbContext.Database.Migrate();

Предупреждение

  • Такой подход не является универсальным.This approach isn't for everyone. Хотя он отлично подходит для приложений с локальной базой данных, большинству приложений требуется более надежная стратегия развертывания, такая как создание скриптов SQL.While it's great for apps with a local database, most applications will require more robust deployment strategy like generating SQL scripts.
  • Не вызывайте EnsureCreated() перед Migrate().Don't call EnsureCreated() before Migrate(). EnsureCreated() обходит миграции, чтобы создать схему, что приводит к сбою Migrate().EnsureCreated() bypasses Migrations to create the schema, which causes Migrate() to fail.

Следующие шагиNext steps

Для получения дополнительной информации см. Справочник по инструментам Entity Framework Core — EF Core.For more information, see Справочник по инструментам Entity Framework Core — EF Core.