Verwalten von Migrationen

Wenn sich Ihr Modell ändert, werden Migrationen als Teil der normalen Entwicklung hinzugefügt und entfernt, und die Migrationsdateien werden in die Quellcodeverwaltung Ihres Projekts eingecheckt. Zum Verwalten von Migrationen müssen Sie zuerst die EF Core-Befehlszeilentools installieren.

Hinzufügen einer Migration

Nachdem Ihr Modell geändert wurde, können Sie eine Migration für diese Änderung hinzufügen:

dotnet ef migrations add AddBlogCreatedTimestamp

Add-Migration AddBlogCreatedTimestamp

Der Migrationsname kann wie eine Commitnachricht in einem Versionssteuerungssystem verwendet werden. Sie können beispielsweise einen Namen wie "AddBlogCreatedTimestamp " auswählen, wenn die Änderung eine neue CreatedTimestamp Eigenschaft für Ihre Blog Entität ist.

Drei Dateien werden zu Ihrem Projekt im Migrations-Verzeichnis hinzugefügt.

• XXXXXXXXXXXXXX_AddBlogCreatedTimestamp.cs- Die Hauptmigrationsdatei. Enthält die vorgänge, die zum Anwenden der Migration (in Up) und zum Wiederherstellen der Migration (in Down) erforderlich sind.
• XXXXXXXXXXXXXX_AddBlogCreatedTimestamp.Designer.cs- Die Migrationsmetadatendatei. Enthält Informationen, die von EF verwendet werden.
• MyContextModelSnapshot.cs – Eine Momentaufnahme Ihres aktuellen Modells. Wird verwendet, um zu bestimmen, was beim Hinzufügen der nächsten Migration geändert wurde.

Der Zeitstempel im Dateinamen hilft ihnen, sie chronologisch sortiert zu halten, damit Sie den Fortschritt der Änderungen sehen können.

Namespaces

Sie können Migrationsdateien verschieben und deren Namespace manuell ändern. Neue Migrationen werden als gleichgeordnete Elemente der letzten Migration erstellt. Alternativ können Sie das Verzeichnis zum Zeitpunkt der Generierung wie folgt angeben:

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

Add-Migration InitialCreate -OutputDir Your\Directory

Erstellen und Anwenden einer Migration in einem Schritt

Der dotnet ef database update Befehl unterstützt das Erstellen und Anwenden einer Migration in einem einzigen Schritt mithilfe der --add Option. Dabei wird Roslyn verwendet, um die Migration zur Laufzeit zu kompilieren, wodurch Szenarien wie .NET Aspire und containerisierte Anwendungen ermöglicht werden, bei denen die Anwendung nicht beendet und neu kompiliert werden kann:

dotnet ef database update InitialCreate --add

dotnet ef database update AddProducts --add --output-dir Migrations/Products --namespace MyApp.Migrations

Update-Database -Migration InitialCreate -Add

Mit diesem Befehl wird eine neue Migration mit dem angegebenen Namen erstellt, mithilfe von Roslyn kompiliert und sofort auf die Datenbank angewendet. Die Migrationsdateien werden weiterhin auf dem Datenträger für die Quellcodeverwaltung und zukünftige Neukompilierung gespeichert.

Wenn keine ausstehenden Modelländerungen erkannt werden, wendet der Befehl vorhandene ausstehende Migrationen an, ohne eine neue zu erstellen.

Anpassen des Migrationscodes

Während EF Core im Allgemeinen genaue Migrationen erstellt, sollten Sie den Code immer überprüfen und sicherstellen, dass er der gewünschten Änderung entspricht. in einigen Fällen ist es sogar notwendig, dies zu tun.

Spaltenumbenennungen

Ein bemerkenswertes Beispiel, bei dem das Anpassen von Migrationen erforderlich ist, ist die Umbenennung einer Eigenschaft. Wenn Sie beispielsweise eine Eigenschaft von Name in FullName umbenennen, generiert EF Core die folgende Migration:

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

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

EF Core kann im Allgemeinen nicht wissen, wann die Absicht besteht, eine Spalte abzulegen und eine neue zu erstellen (zwei separate Änderungen), und wann eine Spalte umbenannt werden soll. Wenn die oben genannte Migration as-isangewendet wird, gehen alle Ihre Kundennamen verloren. Um eine Spalte umzubenennen, ersetzen Sie die oben generierte Migration durch Folgendes:

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

Datenvorgänge

Migrationen können Daten verschieben und das Schema ändern. Wählen Sie den Vorgang basierend darauf aus, ob die Werte bekannt sind, wenn die Migration geschrieben wird:

• Verwenden Sie InsertData, UpdateData, und DeleteData für feste Werte und Zeilen, die durch explizite Schlüssel identifiziert werden. EF Core übersetzt diese Vorgänge in anbieterspezifische SQL, sodass sie auch beim Generieren von Skripts und Bundles funktionieren.
• Wird verwendet Sql , wenn die neuen Werte aus vorhandenen Datenbankdaten berechnet werden müssen. SQL-Syntax kann je nach Anbieter unterschiedlich sein; bei Bedarf verzweigen MigrationBuilder.ActiveProvider .
• Definieren Sie einen benutzerdefinierten Migrationsvorgang , wenn ein wiederverwendbarer Vorgang eine anbieterspezifische SQL-Generierung benötigt.

Verwenden Sie nicht die aktuellen DbContext ODER Entitäts-CLR-Typen, um Daten in einer Migration zu verschieben. Historische Migrationen müssen weiterhin kompiliert und sich verhalten, nachdem diese Typen geändert oder entfernt wurden.

Transformieren vorhandener Daten

Bewahren Sie beim Ersetzen von Spalten die Quelldaten auf, bis das Ziel aufgefüllt wurde:

1. Fügen Sie die Zielspalte als Nullwerte hinzu.
2. Füllen Sie sie aus den vorhandenen Spalten auf.
3. Legen Sie bei Bedarf die Zielspalte fest.
4. Legen Sie die Quellspalten ab.

Die folgende Migration implementiert diese Sequenz für SQL Server und SQLite:

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

if (migrationBuilder.ActiveProvider == "Microsoft.EntityFrameworkCore.SqlServer")
{
    migrationBuilder.Sql(
        """
        UPDATE [Customers]
        SET [FullName] = [FirstName] + N' ' + [LastName];
        """);
}
else if (migrationBuilder.ActiveProvider == "Microsoft.EntityFrameworkCore.Sqlite")
{
    migrationBuilder.Sql(
        """
        UPDATE "Customers"
        SET "FullName" = "FirstName" || ' ' || "LastName";
        """);
}
else
{
    throw new NotSupportedException(
        $"Data migration is not implemented for provider {migrationBuilder.ActiveProvider}.");
}

migrationBuilder.AlterColumn<string>(
    name: "FullName",
    table: "Customers",
    nullable: false,
    oldClrType: typeof(string),
    oldNullable: true);

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

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

Fügen Sie für jeden Anbieter, den die Anwendung unterstützt, eine Verzweigung hinzu. Das Auslösen für einen unbekannten Anbieter ist sicherer als die automatische Anwendung einer unvollständigen Migration. Erstellen Sie SQL nicht aus nicht vertrauenswürdigen Werten; Die Sql-Migration wird mit Schemaänderungsberechtigungen ausgeführt.

Einige Transformationen können nicht rückgängig gemacht werden, ohne Informationen zu verlieren. Implementieren Sie Down nur, wenn die ursprünglichen Werte sicher rekonstruiert werden können. Andernfalls schlagen Sie explizit fehl und erfordern das Wiederherstellen der Daten aus einer Sicherung als Teil der Rollbackprozedur.

Einfügen von festen Daten

Wird verwendet InsertData , wenn die Schlüssel und Werte bekannt sind, wenn die Migration geschrieben wird:

migrationBuilder.InsertData(
    table: "Countries",
    columns: new[] { "CountryId", "Name" },
    values: new object[,]
    {
        { 1, "United States" },
        { 2, "Canada" }
    });

Die entsprechende Down Methode sollte mit denselben Schlüsseln aufgerufen werden DeleteData .

Aktualisieren von festen Daten

UpdateData identifiziert eine Zeile anhand des Schlüssels und legt eine oder mehrere Spalten auf feste Werte fest:

migrationBuilder.UpdateData(
    table: "Countries",
    keyColumn: "CountryId",
    keyValue: 1,
    column: "Name",
    value: "United States of America");

Die Down Methode sollte die vorherigen Werte wiederherstellen.

Löschen von festen Daten

DeleteData identifiziert auch Zeilen nach Schlüssel:

migrationBuilder.DeleteData(
    table: "Countries",
    keyColumn: "CountryId",
    keyValue: 2);

Wenn die Löschung umkehrbar sein muss, sollte die Down Methode zum Wiederherstellen jedes gelöschten Werts verwendet InsertData werden. Diese Vorgänge fragen nicht den aktuellen Datenbankstatus ab; Verwenden Sql oder Initialisierungszeit-Seeding, wenn das Verhalten von vorhandenen Daten abhängt.

Willkürliche Änderungen über Roh-SQL

Raw SQL kann auch zum Verwalten von Datenbankobjekten verwendet werden, die EF Core nicht kennt. Fügen Sie dazu eine Migration hinzu, ohne eine Modelländerung vorzunehmen; Eine leere Migration wird generiert, die Sie dann mit unformatierten SQL-Vorgängen auffüllen können.

Die folgende Migration erstellt beispielsweise eine gespeicherte SQL Server-Prozedur:

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

Dies kann verwendet werden, um jeden Aspekt Ihrer Datenbank zu verwalten, einschließlich:

• Gespeicherte Prozeduren
• Volltextsuche
• Functions
• Triggers
• Views

In den meisten Fällen umschließt EF Core bei der Anwendung von Migrationen automatisch jede Migration in eine eigene Transaktion. Leider können einige Migrationsvorgänge nicht innerhalb einer Transaktion in einigen Datenbanken ausgeführt werden; in diesen Fällen können Sie die Transaktion deaktivieren, indem Sie sie suppressTransaction: trueübergebenmigrationBuilder.Sql.

Entfernen einer Migration

Manchmal fügen Sie eine Migration hinzu und stellen fest, dass Sie zusätzliche Änderungen an Ihrem EF Core-Modell vornehmen müssen, bevor Sie sie anwenden. Verwenden Sie diesen Befehl, um die letzte Migration zu entfernen.

dotnet ef migrations remove

Remove-Migration

Nachdem Sie die Migration entfernt haben, können Sie die zusätzlichen Modelländerungen vornehmen und sie erneut hinzufügen.

Wenn die Migration lokal angewendet wurde

Aktualisieren Sie bei einer einwegbaren Entwicklungsdatenbank zuerst die Datenbank auf die vorherige Migration, und entfernen Sie dann die Migration aus dem Projekt. Wird beim Entfernen der ersten Migration als Ziel verwendet 0 .

dotnet ef database update PreviousMigration
dotnet ef migrations remove

dotnet ef migrations remove --force

Update-Database PreviousMigration
Remove-Migration

Remove-Migration -Force

Wenn die Migration auf eine freigegebene Datenbank angewendet wurde

Löschen Sie keine Migration, die auf eine freigegebene, Test- oder Produktionsdatenbank angewendet wurde. Behalten Sie in der Regel die Migration im Projekt bei, und fügen Sie eine neue Korrekturmigration hinzu. Wenn ein geplantes Rollback erforderlich ist, führen Sie das Rollback aus, während der ursprüngliche Migrationscode noch verfügbar ist, und koordinieren Sie die Anwendungs- und Datenbankbereitstellung.

Entfernen einer älteren nicht angewendeten Migration

Die Tools entfernen nur die neueste Migration. Löschen Sie keine Migration aus der Mitte der Sequenz, und bearbeiten Sie die Modellmomentaufnahme manuell. Wenn die Migration und jede Migration nach der Veröffentlichung aufgehoben und nicht angewendet wurden, entfernen Sie die späteren Migrationen in umgekehrter Reihenfolge, entfernen Sie die unerwünschte Migration, und erstellen Sie dann das Gerüst für die beibehaltenen Modelländerungen erneut.

Wenn die Migrationen in verschiedenen Verzweigungen erstellt wurden, folgen Sie stattdessen dem unterschiedlichen Migrationsstrukturworkflow .

Auflisten von Migrationen

Sie können alle vorhandenen Migrationen wie folgt auflisten:

dotnet ef migrations list

Get-Migration

Sie können den Migrationsstatus auch programmgesteuert prüfen:

var allMigrations = context.Database.GetMigrations();
var appliedMigrations = await context.Database.GetAppliedMigrationsAsync();
var pendingMigrations = await context.Database.GetPendingMigrationsAsync();

GetPendingMigrationsAsync Vergleicht Migrationen in der konfigurierten Migrationsassembly mit den in der Zieldatenbank aufgezeichneten Migrationen. Es erkennt keine Modelländerungen, die in einer Migration nicht erfasst wurden. verwenden Sie dazu die nachstehende Überprüfung der ausstehenden Modelländerungen.

Überprüfen auf ausstehende Modelländerungen

Manchmal sollten Sie überprüfen, ob seit der letzten Migration Modelländerungen vorgenommen wurden. Dies kann Ihnen helfen, zu wissen, wann Sie oder ein Teamkollege vergessen haben, eine Migration hinzuzufügen. Eine Möglichkeit, dies zu tun, ist die Verwendung dieses Befehls.

dotnet ef migrations has-pending-model-changes

Sie können diese Überprüfung auch mithilfe von context.Database.HasPendingModelChanges() programmgesteuert durchführen. Dies kann verwendet werden, um einen Komponententest zu schreiben, der fehlschlägt, wenn Sie vergessen, eine Migration hinzuzufügen.

Zurücksetzen aller Migrationen

In einigen extremen Fällen kann es notwendig sein, alle Migrationen zu entfernen und von vorn zu beginnen. Dies kann ganz einfach erfolgen, indem Sie den Ordner "Migrationen " löschen und Ihre Datenbank ablegen. An diesem Punkt können Sie eine neue anfängliche Migration erstellen, die Ihr gesamtes aktuelles Schema enthält.

Es ist auch möglich, alle Migrationen zurückzusetzen und eine einzelne zu erstellen, ohne Ihre Daten zu verlieren. Dies wird als Migrationen bezeichnet und umfasst einige manuelle Arbeit. EF Core stellt derzeit keinen automatisierten Befehl zur Verfügung; siehe dotnet/efcore#2174.

1. Sichern Sie Ihre Datenbank, falls ein Fehler auftritt.
2. Löschen Sie in Ihrer Datenbank alle Zeilen aus der Migrationsverlaufstabelle (z. B. DELETE FROM [__EFMigrationsHistory] in SQL Server).
3. Löschen Sie Ihren Migrations-Ordner.
4. Erstellen Sie eine neue Migration, und generieren Sie dafür ein SQL-Skript (dotnet ef migrations script).
5. Fügen Sie eine einzelne Zeile in den Migrationsverlauf ein, um aufzuzeichnen, dass die erste Migration bereits angewendet wurde, da Ihre Tabellen bereits vorhanden sind. Das Einfügen von SQL ist der letzte Vorgang im oben generierten SQL-Skript und sieht wie folgt aus (vergessen Sie nicht, die Werte zu aktualisieren):

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

Überprüfen Sie vor der Überprüfung, ob jede bereitgestellte Datenbank bei einer bekannten Migration vorhanden ist, und sichern Sie sie. Neue Datenbanken müssen aus der neuen anfänglichen Migration erstellt werden, während vorhandene Datenbanken die Ersetzungsmigration aufgezeichnet haben müssen, ohne Schemavorgänge auszuführen, die bereits angewendet wurden. Testen Sie beide Pfade vor der Bereitstellung.

Weitere Ressourcen

• Referenz zu Entity Framework Core-Tools – .NET CLI : Enthält Befehle zum Aktualisieren, Ablegen, Hinzufügen, Entfernen und vieles mehr.
• Referenz zu Entity Framework Core-Tools – Paket-Manager-Konsole in Visual Studio : Enthält Befehle zum Aktualisieren, Ablegen, Hinzufügen, Entfernen und vieles mehr.