MigrationenMigrations

Ein Datenmodell ändert sich im Lauf der Entwicklung und ist nicht mehr synchron mit der Datenbank.A data model changes during development and gets out of sync with the database. Sie können die Datenbank verwerfen und EF eine neue erstellen lassen, die dem Modell entspricht, aber dieses Vorgehen führt zum Verlust von Daten.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. Das Migrations-Feature in EF Core bietet einen Weg, das Datenbankschema inkrementell zu aktualisieren, um es mit dem Datenmodell der Anwendung synchron zu halten und zugleich die vorhandenen Daten in der Datenbank beizubehalten.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.

Migrations enthält Befehlszeilentools und APIs, die Sie bei den folgenden Aufgaben unterstützen:Migrations includes command-line tools and APIs that help with the following tasks:

Installieren der ToolsInstall the tools

Installieren Sie die Befehlszeilentools:Install the command-line tools:

Erstellen einer MigrationCreate a migration

Nach dem Definieren des Ausgangsmodells ist der Zeitpunkt gekommen, die Datenbank zu erstellen.After you've defined your initial model, it's time to create the database. Um eine anfängliche Migration hinzuzufügen, führen Sie den folgenden Befehl aus:To add an initial migration, run the following command.

Add-Migration InitialCreate
dotnet ef migrations add InitialCreate

Drei Dateien werden Ihrem Projekt im Verzeichnis Migrationen hinzugefügt:Three files are added to your project under the Migrations directory:

  • XXXXXXXXXXXXXX_InitialCreate.cs: Die wichtigste Migrationsdatei.XXXXXXXXXXXXXX_InitialCreate.cs--The main migrations file. Enthält die Vorgänge, die zum Durchführen der Migration (in Up()) und Rückgängigmachen (in Down()) erforderlich sind.Contains the operations necessary to apply the migration (in Up()) and to revert it (in Down()).
  • XXXXXXXXXXXXXX_InitialCreate.Designer.cs: Die Metadatendatei für die Migration.XXXXXXXXXXXXXX_InitialCreate.Designer.cs--The migrations metadata file. Enthält Informationen, die vom EF verwendet werden.Contains information used by EF.
  • MyContextModelSnapshot.cs – Eine Momentaufnahme des aktuellen Modells.MyContextModelSnapshot.cs--A snapshot of your current model. Diese wird verwendet, um festzustellen, was sich beim Hinzufügen der nächsten Migration geändert hat.Used to determine what changed when adding the next migration.

Mit dem Zeitstempel im Dateinamen können Migrationen chronologisch angeordnet werden, sodass Sie den Fortschritt der Änderungen mitverfolgen können.The timestamp in the filename helps keep them ordered chronologically so you can see the progression of changes.

Tipp

Es steht Ihnen frei, Migrationsdateien zu verschieben und ihren Namespace zu ändern.You are free to move Migrations files and change their namespace. Neue Migrationen werden als gleichgeordnete Elemente der letzten Migration erstellt.New migrations are created as siblings of the last migration.

Aktualisieren der DatenbankUpdate the database

Als Nächstes führen Sie für die Datenbank die Migration durch, um das Schema zu erstellen.Next, apply the migration to the database to create the schema.

Update-Database
dotnet ef database update

Anpassen des MigrationscodesCustomize migration code

Nachdem Sie Änderungen an Ihrem EF Core-Modell vorgenommen haben, ist das Datenbankschema möglicherweise nicht mehr synchron. Fügen Sie eine andere Migration hinzu, um es auf dem neuesten Stand zu bringen.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. Der Migrationsname kann wie eine Commitnachricht in einem Versionskontrollsystem verwendet werden.The migration name can be used like a commit message in a version control system. Beispielsweise können Sie einen Namen wie AddProductReviews wählen, wenn die Änderung eine neue Entitätsklasse für Rezensionen ist.For example, you might choose a name like AddProductReviews if the change is a new entity class for reviews.

Add-Migration AddProductReviews
dotnet ef migrations add AddProductReviews

Nachdem das Gerüst für die Migration erstellt (Code für sie generiert) wurde, prüfen Sie den Code auf Genauigkeit und fügen Sie alle für seine korrekte Anwendung erforderlichen Änderungen hinzu, bzw. entfernen oder bearbeiten Sie sie.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.

Beispielsweise kann eine Migration die folgenden Vorgänge beinhalten: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);

Durch diese Vorgänge wird zwar Kompatibilität mit dem Datenbankschema hergestellt, die bestehenden Kundennamen werden jedoch nicht gespeichert.While these operations make the database schema compatible, they don't preserve the existing customer names. Um dies zu korrigieren, schreiben Sie es wie folgt neu: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");

Tipp

Der Einrüstvorgang der Migration warnt, wenn bei einem Vorgang Datenverlust eintreten kann (etwa beim Verwerfen einer Spalte).The migration scaffolding process warns when an operation might result in data loss (like dropping a column). Wenn diese Warnung angezeigt wird, überprüfen Sie den Migrationscode besonders gründlich auf Genauigkeit.If you see that warning, be especially sure to review the migrations code for accuracy.

Führen Sie für die Datenbank die Migration mit dem entsprechenden Befehl durch.Apply the migration to the database using the appropriate command.

Update-Database
dotnet ef database update

Leere MigrationenEmpty migrations

Manchmal ist es sinnvoll, eine Migration hinzuzufügen, ohne Modelländerungen vorzunehmen.Sometimes it's useful to add a migration without making any model changes. In diesem Fall werden durch das Hinzufügen einer neuen Migration Codedateien mit leeren Klassen erstellt.In this case, adding a new migration creates code files with empty classes. Sie können diese Migration anpassen, um Vorgänge durchzuführen, die sich nicht direkt auf das EF Core-Modell beziehen.You can customize this migration to perform operations that don't directly relate to the EF Core model. Einige Dinge, die Sie vielleicht auf diese Weise handhaben wollen, sind Folgende:Some things you might want to manage this way are:

  • VolltextsucheFull-Text Search
  • FunktionenFunctions
  • Gespeicherte ProzedurenStored procedures
  • TriggerTriggers
  • AnsichtenViews

Entfernen einer MigrationRemove a migration

Es kann vorkommen, dass Sie eine Migration hinzufügen und feststellen, dass Sie zusätzliche Änderungen an Ihrem EF Core-Modell vornehmen müssen, bevor Sie diese durchführen.Sometimes you add a migration and realize you need to make additional changes to your EF Core model before applying it. Um die letzte Migration zu entfernen, verwenden Sie diesen Befehl.To remove the last migration, use this command.

Remove-Migration
dotnet ef migrations remove

Nachdem Sie die Migration entfernt haben, können Sie die zusätzlichen Modelländerungen vornehmen und sie erneut hinzufügen.After removing the migration, you can make the additional model changes and add it again.

Rückgängigmachen einer MigrationRevert a migration

Wenn Sie bereits eine Migration (oder mehrere Migrationen) für die Datenbank durchgeführt haben, diese jedoch rückgängig machen müssen, können Sie mit demselben Befehl Migrationen durchführen, aber den Namen der Migration angeben, für die Sie ein Rollback ausführen möchten.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.

Update-Database LastGoodMigration
dotnet ef database update LastGoodMigration

Generieren von SQL-SkriptsGenerate SQL scripts

Wenn Sie Ihre Migrationen debuggen oder in einer Produktionsdatenbank bereitstellen, ist es sinnvoll, ein SQL-Skript zu generieren.When debugging your migrations or deploying them to a production database, it's useful to generate a SQL script. Das Skript kann dann weiter auf Genauigkeit überprüft und auf die Anforderungen einer Produktionsdatenbank abgestimmt werden.The script can then be further reviewed for accuracy and tuned to fit the needs of a production database. Das Skript kann auch in Verbindung mit einer Bereitstellungstechnologie verwendet werden.The script can also be used in conjunction with a deployment technology. Der grundlegende Befehl lautet wie folgt:The basic command is as follows.

Script-Migration
dotnet ef migrations script

Es gibt mehrere Optionen für diesen Befehl.There are several options to this command.

Die from-Migration sollte die letzte Migration sein, die vor der Skriptausführung für die Datenbank durchgeführt wurde.The from migration should be the last migration applied to the database before running the script. Wenn keine Migrationen durchgeführt wurden, geben Sie 0 an (dies ist die Standardeinstellung).If no migrations have been applied, specify 0 (this is the default).

Die to-Migration ist die letzte Migration, die nach der Skriptausführung für die Datenbank durchgeführt wurde.The to migration is the last migration that will be applied to the database after running the script. Dies ist standardmäßig die letzte Migration in Ihrem Projekt.This defaults to the last migration in your project.

Optional kann ein idempotent-Skript generiert werden.An idempotent script can optionally be generated. Dieses Skript wendet nur Migrationen an, wenn sie nicht bereits für die Datenbank durchgeführt wurden.This script only applies migrations if they haven't already been applied to the database. Dies ist hilfreich, wenn Sie nicht genau wissen, welche Migration für die Datenbank zuletzt durchgeführt wurde oder wenn Bereitstellungen in mehreren Datenbanken, die sich jeweils in unterschiedlichen Migrationen befinden, erfolgen.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.

Anwenden von Migrationen zur LaufzeitApply migrations at runtime

Einige Apps sollten beim Start oder bei der ersten Ausführung Migrationen zur Runtime durchführen.Some apps may want to apply migrations at runtime during startup or first run. Dies ist mit der Methode Migrate() möglich.Do this using the Migrate() method.

Diese Methode basiert auf dem IMigrator-Dienst, der für erweiterte Szenarien verwendet werden kann.This method builds on top of the IMigrator service, which can be used for more advanced scenarios. Verwenden Sie DbContext.GetService<IMigrator>(), um darauf zugreifen.Use DbContext.GetService<IMigrator>() to access it.

myDbContext.Database.Migrate();

Warnung

  • Diese Vorgehensweise ist nicht für alle geeignet.This approach isn't for everyone. Diese eignet sich zwar ideal für Apps mit einer lokalen Datenbank, doch die meisten Anwendungen erfordern zuverlässigere Bereitstellungsstrategien wie etwa durch das Generieren von SQL-Skripts.While it's great for apps with a local database, most applications will require more robust deployment strategy like generating SQL scripts.
  • Rufen Sie EnsureCreated() nicht vor Migrate() auf.Don't call EnsureCreated() before Migrate(). EnsureCreated() umgeht Migrationen zum Erstellen von Schemas, was dazu führt, dass Migrate() fehlerhaft ist.EnsureCreated() bypasses Migrations to create the schema, which causes Migrate() to fail.

Nächste SchritteNext steps

Weitere Informationen finden Sie unter Entity Framework Core Tools-Referenz – EF Core.For more information, see Entity Framework Core Tools-Referenz – EF Core.