Teil 4: Razor-Seiten mit EF Core-Migrationen in ASP.NET Core

Von Tom Dykstra, Jon P. Smith und Rick Anderson

Die Web-App Contoso University veranschaulicht, wie Razor-Seiten-Web-Apps mit EF Core und Visual Studio erstellt werden können. Informationen zu den Tutorials finden Sie im ersten Tutorial.

Wenn Probleme auftreten, die Sie nicht beheben können, laden Sie die vollständige App herunter, und vergleichen Sie diesen Code mit dem Code, den Sie anhand des Tutorials erstellt haben.

In diesem Tutorial wird das EF Core-Migrationsfeature für die Verwaltung von Datenmodelländerungen vorgestellt.

Wenn eine neue App entwickelt wird, ändert sich das Datenmodell häufig. Nach jeder Modelländerung ist das Modell nicht mehr synchron mit der Datenbank. In dieser Tutorialreihe wurde zunächst Entity Framework für die Erstellung der Datenbank konfiguriert, falls diese nicht vorhanden ist. Jedes Mal, wenn sich das Datenmodell ändert, muss die Datenbank gelöscht werden. Wenn die App das nächste Mal ausgeführt wird, wird durch den Aufruf von EnsureCreated die Datenbank erneut entsprechend dem neuen Datenmodell erstellt. Die DbInitializer-Klasse wird dann ausgeführt, um das Seeding der neuen Datenbank durchzuführen.

Dieser Ansatz, die DB mit dem Datenmodell synchron zu halten, funktioniert gut, bis die App in der Produktion bereitgestellt werden muss. Wenn die App in der Produktionsumgebung ausgeführt wird, speichert sie in der Regel Daten, die verwaltet werden müssen. Jedes Mal, wenn eine Änderung vorgenommen wird (z.B. wenn eine neue Spalte hinzugefügt wird), kann die App nicht mit einer Testdatenbank starten. Mit dem EF Core-Migrationsfeature wird dieses Problem gelöst, indem EF Core das Datenbankschema aktualisiert, anstatt eine neue Datenbank zu erstellen.

Anstatt die Datenbank bei Änderungen des Datenmodell zu löschen und neu zu erstellen, erfolgt bei der Migration eine Aktualisierung des Schemas und die Beibehaltung vorhandener Daten.

Hinweis

SQLite-Einschränkungen

Dieses Tutorial verwendet nach Möglichkeit das Entity Framework Core-Feature Migrationen. Durch Migrationen wird das Datenbankschema so aktualisiert, dass es den Änderungen am Datenmodell entspricht. Bei Migrationen werden jedoch nur die Änderungen vorgenommen, die von der Datenbank-Engine unterstützt werden, und die Schemaänderungsfunktionen von SQLite sind beschränkt. Zum Beispiel wird Hinzufügen einer Spalten unterstützt, wogegen Entfernen einer Spalte nicht unterstützt wird. Wenn eine Migration zum Entfernen einer Spalte erstellt wird, ist der Befehl ef migrations add erfolgreich, aber der Befehl ef database update schlägt fehl.

Die Problemumgehung für die SQLite-Einschränkungen besteht darin, manuell Migrationscode zu schreiben, um das erneute Erstellen einer Tabelle durchzuführen, wenn sich etwas in der Tabelle ändert. Der Code fließt in die Up- und Down-Methoden für eine Migration ein und umfasst Folgendes:

• Erstellen einer neuen Tabelle.
• Kopieren von Daten aus der alten Tabelle in die neue Tabelle.
• Löschen der alten Tabelle.
• Umbenennen der neuen Tabelle.

Das Schreiben von datenbankspezifischem Code dieses Typs übersteigt den Rahmen dieses Tutorials. Stattdessen wird die Datenbank in diesem Tutorial gelöscht und neu erstellt, wenn der Versuch fehlschlägt, eine Migration anzuwenden. Weitere Informationen finden Sie in den folgenden Ressourcen:

• Einschränkungen des SQLite-EF Core-Datenbankanbieters
• Anpassen des Migrationscodes
• Datenseeding
• SQLite ALTER TABLE-Anweisung

Löschen der Datenbank

Visual Studio

Verwenden Sie SQL Server-Objekt-Explorer (SSOX), um die Datenbank zu löschen, oder führen Sie den folgenden Befehl in der Paket-Manager-Konsole (PMC) aus:

Drop-Database

Visual Studio Code

• Führen Sie in der Eingabeaufforderung den folgenden Befehl aus, um die EF CLI zu installieren:

  dotnet tool install --global dotnet-ef
  

Hinweis

Standardmäßig stellt die Architektur der zu installierenden .NET-Binärdateien die derzeit ausgeführte Betriebssystemarchitektur dar. Informationen zum Angeben einer anderen Betriebssystemarchitektur finden Sie unter dotnet tool install, --arch option. Weitere Informationen finden Sie unter dem GitHub Issue dotnet/docs #29262.

• Navigieren Sie in der Eingabeaufforderung zum Projektordner. Der Projektordner enthält die Datei ContosoUniversity.csproj.

• Löschen Sie die Datei CU.db, oder führen Sie den folgenden Befehl aus:

  dotnet ef database drop --force
  

Erstellen einer ursprünglichen Migration

Visual Studio

Führen Sie die folgenden Befehle in der PMC aus:

Add-Migration InitialCreate
Update-Database

Visual Studio Code

Stellen Sie sicher, dass sich die Eingabeaufforderung im Projektordner befindet, und führen Sie die folgenden Befehle aus:

dotnet ef migrations add InitialCreate
dotnet ef database update

Entfernen von EnsureCreated

Diese Tutorialreihe hat mit der Verwendung von EnsureCreated begonnen. EnsureCreated erstellt keine Migrationsverlaufstabelle und kann daher nicht mit Migrationen verwendet werden. EnsureCreated dient zum Testen oder schnellen Erstellen von Prototypen, wenn die Datenbank häufig gelöscht und neu erstellt wird.

Ab diesem Zeitpunkt werden die Tutorials Migrationen verwenden.

Löschen Sie in Program.cs das folgende Element:

context.Database.EnsureCreated();

Führen Sie die App aus, und stellen Sie sicher, dass für die Datenbank ein Seeding durchgeführt wird.

Up- und Down-Methoden

Der EF Core-Befehl migrations add hat Code zum Erstellen der Datenbank generiert. Der Migrationscode befindet sich in der Migrations\<timestamp>_InitialCreate.cs-Datei. Die Methode Up der Klasse InitialCreate erstellt die Datenbanktabellen, die den Datenmodell-Entitätenmengen entsprechen. Die Methode Down löscht diese, wie im folgenden Beispiel dargestellt:

using System;
using Microsoft.EntityFrameworkCore.Metadata;
using Microsoft.EntityFrameworkCore.Migrations;

namespace ContosoUniversity.Migrations
{
    public partial class InitialCreate : Migration
    {
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.CreateTable(
                name: "Course",
                columns: table => new
                {
                    CourseID = table.Column<int>(nullable: false),
                    Title = table.Column<string>(nullable: true),
                    Credits = table.Column<int>(nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Course", x => x.CourseID);
                });

            migrationBuilder.CreateTable(
                name: "Student",
                columns: table => new
                {
                    ID = table.Column<int>(nullable: false)
                        .Annotation("SqlServer:ValueGenerationStrategy", SqlServerValueGenerationStrategy.IdentityColumn),
                    LastName = table.Column<string>(nullable: true),
                    FirstMidName = table.Column<string>(nullable: true),
                    EnrollmentDate = table.Column<DateTime>(nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Student", x => x.ID);
                });

            migrationBuilder.CreateTable(
                name: "Enrollment",
                columns: table => new
                {
                    EnrollmentID = table.Column<int>(nullable: false)
                        .Annotation("SqlServer:ValueGenerationStrategy", SqlServerValueGenerationStrategy.IdentityColumn),
                    CourseID = table.Column<int>(nullable: false),
                    StudentID = table.Column<int>(nullable: false),
                    Grade = table.Column<int>(nullable: true)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Enrollment", x => x.EnrollmentID);
                    table.ForeignKey(
                        name: "FK_Enrollment_Course_CourseID",
                        column: x => x.CourseID,
                        principalTable: "Course",
                        principalColumn: "CourseID",
                        onDelete: ReferentialAction.Cascade);
                    table.ForeignKey(
                        name: "FK_Enrollment_Student_StudentID",
                        column: x => x.StudentID,
                        principalTable: "Student",
                        principalColumn: "ID",
                        onDelete: ReferentialAction.Cascade);
                });

            migrationBuilder.CreateIndex(
                name: "IX_Enrollment_CourseID",
                table: "Enrollment",
                column: "CourseID");

            migrationBuilder.CreateIndex(
                name: "IX_Enrollment_StudentID",
                table: "Enrollment",
                column: "StudentID");
        }

        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropTable(
                name: "Enrollment");

            migrationBuilder.DropTable(
                name: "Course");

            migrationBuilder.DropTable(
                name: "Student");
        }
    }
}

Der vorangehende Code ist für die ursprüngliche Migration bestimmt. Der Code:

• Wurde durch den migrations add InitialCreate-Befehl generiert.
• Wird durch den database update-Befehl ausgeführt.
• Erstellt eine Datenbank für das Datenmodell, das durch die Datenbankkontextklasse angegeben wird.

Der Parameter für den Migrationsnamen (im Beispiel InitialCreate) wird als Dateiname verwendet. Der Migrationsname kann ein beliebiger gültiger Dateiname sein. Es wird empfohlen, ein Wort oder einen Ausdruck auszuwählen, durch das bzw. den der Hintergrund der Migration widergespiegelt wird. Eine Migration, bei der eine Tabelle mit Fachbereichen hinzugefügt wurde, könnte beispielsweise als „AddDepartmentTable“ bezeichnet werden.

Die Migrationsverlaufstabelle

• Verwenden Sie SSOX oder das SQLite-Tool, um die Datenbank zu untersuchen.
• Beachten Sie die zusätzliche Tabelle__EFMigrationsHistory. In der Tabelle __EFMigrationsHistory wird nachverfolgt, welche Migrationen auf die Datenbank angewendet wurden.
• Zeigen Sie die Daten in der Tabelle __EFMigrationsHistory an. Es wird eine Zeile für die erste Migration angezeigt.

Die Momentaufnahme des Datenmodells

Migrationen erstellen eine Momentaufnahme des aktuellen Datenmodells in Migrations/SchoolContextModelSnapshot.cs. Wenn eine Migration hinzugefügt wird, bestimmt EF die vorgenommenen Änderungen, indem das aktuelle Datenmodell mit der Momentaufnahmedatei verglichen wird.

Da die Momentaufnahmedatei den Zustand des Datenmodells nachverfolgt, kann eine Migration nicht durch Löschen der Datei <timestamp>_<migrationname>.cs gelöscht werden. Zum Zurücksetzen der neuesten Migration verwenden Sie den Befehl migrations remove. migrations remove löscht die Migration und stellt sicher, dass die Momentaufnahme ordnungsgemäß zurückgesetzt wird. Weitere Informationen finden Sie unter dotnet ef migrations remove.

Informationen zum Entfernen aller Migrationen finden Sie unter Zurücksetzen aller Migrationen .

Anwenden von Migrationen in der Produktionsumgebung

Es wird empfohlen, dass Produktions-Apps Database.Migrate beim Anwendungsstart nicht aufrufen. Migrate sollte nicht aus einer APP aufgerufen werden, die in einer Serverfarm bereitgestellt wird. Wenn die App auf mehrere Serverinstanzen horizontal hochskaliert wird, ist es schwierig sicherzustellen, dass Datenbankschemaaktualisierungen nicht von mehreren Servern erfolgen oder mit Lese-/Schreibzugriffen einen Konflikt verursachen.

Die Datenbankmigration sollte im Rahmen der Bereitstellung und auf kontrollierte Weise erfolgen. Zu den Ansätzen für die Migration von Produktionsdatenbanken zählen die folgenden:

• Verwendung von Migrationen zur Erstellung von SQL-Skripts und Verwendung der SQL-Skripts bei der Bereitstellung.
• Ausführen von dotnet ef database update über eine kontrollierte Umgebung.

Problembehandlung

Wenn die App SQL Server LocalDB verwendet und die folgende Ausnahme angezeigt wird:

SqlException: Cannot open database "ContosoUniversity" requested by the login.
The login failed.
Login failed for user 'user name'.

Die Lösung kann die Ausführung von dotnet ef database update an einer Eingabeaufforderung sein.

Zusätzliche Ressourcen

• EF Core CLI.
• dotnet ef migrations (CLI-Befehle)
• Paket-Manager-Konsole (Visual Studio)

Nächste Schritte

Im nächsten Tutorial wird das Datenmodell erstellt, und es werden Entitätseigenschaften und neue Entitäten hinzugefügt.

Vorheriges TutorialNächstes Tutorial