Tutorial: Verwenden des Migrationsfeatures: ASP.NET MVC mit EF CoreTutorial: Using the migrations feature - ASP.NET MVC with EF Core

In diesem Tutorial verwenden Sie zunächst die EF Core-Migrationsfeature für die Verwaltung von Datenmodelländerungen.In this tutorial, you start using the EF Core migrations feature for managing data model changes. In späteren Tutorials fügen Sie weitere Migrationen hinzu, wenn Sie das Datenmodell ändern.In later tutorials, you'll add more migrations as you change the data model.

In diesem Tutorial:In this tutorial, you:

  • Erfahren Sie mehr über MigrationenLearn about migrations
  • Ändern der VerbindungszeichenfolgeChange the connection string
  • Erstellen einer ursprünglichen MigrationCreate an initial migration
  • Untersuchen Sie Up- und Down-MethodenExamine Up and Down methods
  • Erfahren Sie mehr über die Datenmodell-MomentaufnahmeLearn about the data model snapshot
  • Anwenden der MigrationApply the migration

Erforderliche KomponentenPrerequisites

Informationen zu MigrationenAbout migrations

Wenn Sie eine neue Anwendung entwickeln, ändert sich Ihr Datenmodell häufig. Jedes Mal, wenn das Datenmodell geändert wird, ist es nicht mehr synchron mit der Datenbank.When you develop a new application, your data model changes frequently, and each time the model changes, it gets out of sync with the database. Sie haben zu Beginn dieser Tutorials Entity Framework für die Erstellung der Datenbank konfiguriert, sofern diese nicht vorhanden war.You started these tutorials by configuring the Entity Framework to create the database if it doesn't exist. Anschließend können Sie bei jeder Datenmodelländerung (beim Hinzufügen, Entfernen oder Ändern von Entitätsklassen oder beim Ändern Ihrer DbContext-Klasse) die Datenbank löschen. EF erstellt dann eine neue Datenbank, die dem Modell entspricht, und startet diese mit Testdaten.Then each time you change the data model -- add, remove, or change entity classes or change your DbContext class -- you can delete the database and EF creates a new one that matches the model, and seeds it with test data.

Diese Methode, bei der die Datenbank mit dem Datenmodell synchron gehalten wird, funktioniert so lange, bis Sie die Anwendung für die Produktion bereitstellen.This method of keeping the database in sync with the data model works well until you deploy the application to production. Wenn sich die Anwendung in der Produktion befindet, speichert sie in der Regel die Daten, die Sie weiter verwenden möchten, da nicht bei jeder Änderung, wie z.B. dem Hinzufügen einer neuen Spalte, alle Daten verloren gehen sollen.When the application is running in production it's usually storing data that you want to keep, and you don't want to lose everything each time you make a change such as adding a new column. Mit der EF Core-Migrationsfeature wird dieses Problem gelöst, indem EF das Datenbankschema aktualisiert, statt eine neue Datenbank zu erstellen.The EF Core Migrations feature solves this problem by enabling EF to update the database schema instead of creating a new database.

Für die Arbeit mit Migrationen können Sie die Paket-Manager-Konsole (Package Manager Console, PMC) oder die Befehlszeilenschnittstelle (Command-Line Interface, CLI) verwenden.To work with migrations, you can use the Package Manager Console (PMC) or the command-line interface (CLI). In diesen Tutorials wird die Verwendungsweise von CLI-Befehlen erläutert.These tutorials show how to use CLI commands. Informationen zur PMC finden Sie am Ende dieses Tutorials.Information about the PMC is at the end of this tutorial.

Ändern der VerbindungszeichenfolgeChange the connection string

Ändern Sie in der Datei appsettings.json in der Verbindungszeichenfolge den Namen der Datenbank in „ContosoUniversity2“ oder in einen anderen Namen, den Sie auf Ihrem Computer noch nicht verwendet haben.In the appsettings.json file, change the name of the database in the connection string to ContosoUniversity2 or some other name that you haven't used on the computer you're using.

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=ContosoUniversity2;Trusted_Connection=True;MultipleActiveResultSets=true"
  },

Durch diese Änderung wird das Projekt eingerichtet, sodass bei der ersten Migration eine neue Datenbank erstellt wird.This change sets up the project so that the first migration will create a new database. Dies ist für die ersten Schritte mit Migrationen nicht erforderlich, aber Sie werden später feststellen, weshalb es sich empfiehlt, entsprechend vorzugehen.This isn't required to get started with migrations, but you'll see later why it's a good idea.

Hinweis

Alternativ zum Ändern des Datenbanknamens können Sie die Datenbank auch löschen.As an alternative to changing the database name, you can delete the database. Verwenden Sie den SQL Server-Objekt-Explorer (SSOX) oder den CLI-Befehl database drop:Use SQL Server Object Explorer (SSOX) or the database drop CLI command:

dotnet ef database drop

Im folgenden Abschnitt wird erläutert, wie CLI-Befehle ausgeführt werden.The following section explains how to run CLI commands.

Erstellen einer ursprünglichen MigrationCreate an initial migration

Speichern Sie Ihre Änderungen, und erstellen Sie das Projekt.Save your changes and build the project. Öffnen Sie anschließend ein Befehlsfenster, und navigieren Sie zu dem Projektordner.Then open a command window and navigate to the project folder. Sie können diesen Vorgang auf folgende Weise beschleunigen:Here's a quick way to do that:

  • Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie aus dem Kontextmenü die Option Ordner in Datei-Explorer öffnen aus.In Solution Explorer, right-click the project and choose Open Folder in File Explorer from the context menu.

    Menüelement „In Datei-Explorer öffnen“

  • Geben Sie in die Adressleiste „cmd“ ein, und drücken Sie die EINGABETASTE.Enter "cmd" in the address bar and press Enter.

    Öffnen des Befehlsfensters

Geben Sie im Befehlsfenster folgenden Befehl ein:Enter the following command in the command window:

dotnet ef migrations add InitialCreate

Im Befehlsfenster wird Ihnen eine Ausgabe wie die folgende angezeigt:You see output like the following in the command window:

info: Microsoft.EntityFrameworkCore.Infrastructure[10403]
      Entity Framework Core 2.2.0-rtm-35687 initialized 'SchoolContext' using provider 'Microsoft.EntityFrameworkCore.SqlServer' with options: None
Done. To undo this action, use 'ef migrations remove'

Hinweis

Wenn Ihnen die Fehlermeldung Es wurde keine ausführbare Datei gefunden, die dem Befehl „dotnet-ef“ entspricht. angezeigt wird, finden Sie unter diesem Blogbeitrag Hilfe zur Problembehandlung.If you see an error message No executable found matching command "dotnet-ef", see this blog post for help troubleshooting.

Wenn Ihnen die Fehlermeldung Auf die Datei „ContosoUniversity.dll“ kann nicht zugegriffen werden, da sie von einem anderen Prozess verwendet wird. angezeigt wird, suchen Sie in der Windows-Taskleiste nach dem Symbol „IIS Express“, klicken Sie mit der rechten Maustaste darauf, und klicken Sie anschließend auf ContosoUniversity > Website beenden.If you see an error message "cannot access the file ... ContosoUniversity.dll because it is being used by another process.", find the IIS Express icon in the Windows System Tray, and right-click it, then click ContosoUniversity > Stop Site.

Untersuchen Sie Up- und Down-MethodenExamine Up and Down methods

Wenn Sie den Befehl migrations add ausgeführt haben, hat EF den Code generiert, mit dem die Datenbank von Grund auf neu erstellt wird.When you executed the migrations add command, EF generated the code that will create the database from scratch. Dieser Code befindet sich im Ordner Migrationen in der Datei <timestamp>_InitialCreate.cs.This code is in the Migrations folder, in the file named <timestamp>_InitialCreate.cs. Mit der Methode Up der InitialCreate-Klasse werden die Datenbanktabellen erstellt, die den Datenmodellentitäten entsprechen, und mit der Methode Down werden die Datenbanktabellen gelöscht (siehe folgendes Beispiel).The Up method of the InitialCreate class creates the database tables that correspond to the data model entity sets, and the Down method deletes them, as shown in the following example.

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

        // Additional code not shown
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropTable(
            name: "Enrollment");
        // Additional code not shown
    }
}

Die Migrationsfunktion ruft die Methode Up auf, um die Datenmodelländerungen für eine Migration zu implementieren.Migrations calls the Up method to implement the data model changes for a migration. Wenn Sie einen Befehl eingeben, um ein Rollback für das Update auszuführen, ruft die Migrationsfunktion die Methode Down auf.When you enter a command to roll back the update, Migrations calls the Down method.

Dieser Code ist für die ursprüngliche Migration vorgesehen, die bei der Eingabe des Befehls migrations add InitialCreate erstellt wurde.This code is for the initial migration that was created when you entered the migrations add InitialCreate command. Der Parameter für den Migrationsnamen (in dem Beispiel „InitialCreate“) wird für den Dateinamen verwendet und kann einen beliebigen Namen haben.The migration name parameter ("InitialCreate" in the example) is used for the file name and can be whatever you want. Es wird empfohlen, ein Wort oder einen Ausdruck auszuwählen, durch das bzw. den der Hintergrund der Migration widergespiegelt wird.It's best to choose a word or phrase that summarizes what is being done in the migration. Sie können einer späteren Migration beispielsweise den Namen „AddDepartmentTable“ geben.For example, you might name a later migration "AddDepartmentTable".

Wenn Sie die ursprüngliche Migration erstellt haben, als die Datenbank bereits vorhanden war, wird der Code für die Datenbankerstellung zwar generiert, allerdings muss er nicht ausgeführt werden, da die Datenbank bereits dem Datenmodell entspricht.If you created the initial migration when the database already exists, the database creation code is generated but it doesn't have to run because the database already matches the data model. Wenn Sie die App in einer anderen Umgebung bereitstellen, in der die Datenbank noch nicht vorhanden ist, wird dieser Code ausgeführt, um Ihre Datenbank zu erstellen. Daher sollte dieser zunächst getestet werden.When you deploy the app to another environment where the database doesn't exist yet, this code will run to create your database, so it's a good idea to test it first. Aus diesem Grund haben Sie den Namen der Datenbank zuvor in der Verbindungszeichenfolge geändert – damit eine Datenbank bei Migrationen von Grund auf neu erstellt werden kann.That's why you changed the name of the database in the connection string earlier -- so that migrations can create a new one from scratch.

Die Momentaufnahme des DatenmodellsThe data model snapshot

Die Migrationsfunktion erstellt unter Migrations/SchoolContextModelSnapshot.cs eine Momentaufnahme des aktuellen Datenbankschemas.Migrations creates a snapshot of the current database schema in Migrations/SchoolContextModelSnapshot.cs. Wenn Sie eine Migration hinzufügen, bestimmt EF die vorgenommenen Änderungen, indem das Datenmodell mit der Momentaufnahmedatei verglichen wird.When you add a migration, EF determines what changed by comparing the data model to the snapshot file.

Verwenden Sie den Befehl dotnet ef migrations remove, wenn Sie eine Migration löschen.When deleting a migration, use the dotnet ef migrations remove command. dotnet ef migrations remove löscht die Migration und stellt sicher, dass die Momentaufnahme ordnungsgemäß zurückgesetzt wird.dotnet ef migrations remove deletes the migration and ensures the snapshot is correctly reset.

Weitere Informationen dazu, wie die Momentaufnahmedatei verwendet wird, finden Sie unter EF Core Migrations in Team Environments (EF Core-Migrationen in Teamumgebungen).See EF Core Migrations in Team Environments for more information about how the snapshot file is used.

Anwenden der MigrationApply the migration

Geben Sie folgenden Befehl in das Befehlsfenster ein, um die Datenbank mit den darin enthaltenen Tabellen zu erstellen.In the command window, enter the following command to create the database and tables in it.

dotnet ef database update

Die Ausgabe des Befehls ähnelt der des Befehls migrations add. Der Unterschied besteht darin, dass Ihnen Protokolle für die SQL-Befehle angezeigt werden, mit denen die Datenbank eingerichtet wird.The output from the command is similar to the migrations add command, except that you see logs for the SQL commands that set up the database. In der folgenden Beispielausgabe werden die meisten Protokolle ausgelassen.Most of the logs are omitted in the following sample output. Wenn diese Detailebene in Protokollnachrichten nicht angezeigt werden soll, können Sie die Protokollebene in der Datei appsettings.Development.json ändern.If you prefer not to see this level of detail in log messages, you can change the log level in the appsettings.Development.json file. Weitere Informationen finden Sie unter Protokollierung in ASP.NET Core.For more information, see Protokollierung in ASP.NET Core.

info: Microsoft.EntityFrameworkCore.Infrastructure[10403]
      Entity Framework Core 2.2.0-rtm-35687 initialized 'SchoolContext' using provider 'Microsoft.EntityFrameworkCore.SqlServer' with options: None
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (274ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
      CREATE DATABASE [ContosoUniversity2];
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (60ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
      IF SERVERPROPERTY('EngineEdition') <> 5
      BEGIN
          ALTER DATABASE [ContosoUniversity2] SET READ_COMMITTED_SNAPSHOT ON;
      END;
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (15ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      CREATE TABLE [__EFMigrationsHistory] (
          [MigrationId] nvarchar(150) NOT NULL,
          [ProductVersion] nvarchar(32) NOT NULL,
          CONSTRAINT [PK___EFMigrationsHistory] PRIMARY KEY ([MigrationId])
      );

<logs omitted for brevity>

info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (3ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      INSERT INTO [__EFMigrationsHistory] ([MigrationId], [ProductVersion])
      VALUES (N'20190327172701_InitialCreate', N'2.2.0-rtm-35687');
Done.

Verwenden Sie den SQL Server-Objekt-Explorer, um die Datenbank wie im ersten Tutorial zu untersuchen.Use SQL Server Object Explorer to inspect the database as you did in the first tutorial. Sie werden feststellen, dass die Tabelle „__EFMigrationsHistory“ hinzugefügt wurde, in der nachverfolgt wird, welche Migrationen auf die Datenbank angewendet worden sind.You'll notice the addition of an __EFMigrationsHistory table that keeps track of which migrations have been applied to the database. Wenn Sie die Daten in dieser Tabelle anzeigen, ist eine Zeile für die erste Migration zu sehen.View the data in that table and you'll see one row for the first migration. (Im letzten Protokoll im vorgehenden Beispiel der CLI-Ausgabe wird die INSERT-Anweisung angezeigt, mit der diese Zeile erstellt wird.)(The last log in the preceding CLI output example shows the INSERT statement that creates this row.)

Führen Sie die Anwendung aus, um zu überprüfen, ob alles wie gewohnt funktioniert.Run the application to verify that everything still works the same as before.

Indexseite „Studenten“

Vergleich von CLI und PMCCompare CLI and PMC

Die EF-Tools für die Verwaltung von Migrationen sind über .NET Core-CLI-Befehle oder über PowerShell-Cmdlets im Visual Studio-Fenster Paket-Manager-Console (PMC) verfügbar.The EF tooling for managing migrations is available from .NET Core CLI commands or from PowerShell cmdlets in the Visual Studio Package Manager Console (PMC) window. In diesem Tutorial wird die Verwendungsweise der CLI erläutert. Sie können aber auch die PMC verwenden, wenn Sie diese bevorzugen.This tutorial shows how to use the CLI, but you can use the PMC if you prefer.

Die EF-Befehle für die PMC-Befehle sind im Paket Microsoft.EntityFrameworkCore.Tools enthalten.The EF commands for the PMC commands are in the Microsoft.EntityFrameworkCore.Tools package. Dieses Paket ist im Microsoft.AspNetCore.App-Metapaket enthalten, weshalb Sie keinen Paketverweis hinzufügen müssen, wenn Ihre App über einen Paketverweis für Microsoft.AspNetCore.App verfügt.This package is included in the Microsoft.AspNetCore.App metapackage, so you don't need to add a package reference if your app has a package reference for Microsoft.AspNetCore.App.

Wichtig: Dieses Paket ist nicht mit dem Paket identisch, das Sie für die CLI durch Bearbeitung der CSPROJ-Datei installiert haben.Important: This isn't the same package as the one you install for the CLI by editing the .csproj file. Der Name dieses Pakets endet mit Tools, im Gegensatz zum Namen des CLI-Pakets, der mit Tools.DotNet endet.The name of this one ends in Tools, unlike the CLI package name which ends in Tools.DotNet.

Weitere Informationen zu CLI-Befehlen finden Sie unter .NET Core-CLI.For more information about the CLI commands, see .NET Core CLI.

Weitere Informationen zu den PMC-Befehlen finden Sie unter Paket-Manager-Konsole (Visual Studio).For more information about the PMC commands, see Package Manager Console (Visual Studio).

Abrufen des CodesGet the code

Download or view the completed app (Herunterladen oder anzeigen der vollständigen App).Download or view the completed application.

Nächster SchrittNext step

In diesem Tutorial:In this tutorial, you:

  • Haben Sie mehr über Migrationen erfahrenLearned about migrations
  • Haben Sie mehr über NuGet-Migrationspakete erfahrenLearned about NuGet migration packages
  • Haben Sie die Verbindungszeichenfolge geändertChanged the connection string
  • Haben Sie eine ursprüngliche Migration erstelltCreated an initial migration
  • Haben Sie Up- und Down-Methoden untersuchtExamined Up and Down methods
  • Haben Sie mehr über die Datenmodell-Momentaufnahme erfahrenLearned about the data model snapshot
  • Haben Sie die Migration angewandtApplied the migration

Fahren Sie mit dem nächsten Tutorial fort, um fortgeschrittenere Themen zum Erweitern des Datenmodells kennenzulernen.Advance to the next tutorial to begin looking at more advanced topics about expanding the data model. Dabei werden Sie weitere Migrationen erstellen und anwenden.Along the way you'll create and apply additional migrations.