Tutoriel : Utilisation de la fonctionnalité de migrations - ASP.NET MVC avec EF CoreTutorial: Using the migrations feature - ASP.NET MVC with EF Core

Dans ce didacticiel, vous utilisez la fonctionnalité Migrations d’EF Core pour gérer les modifications du modèle de données.In this tutorial, you start using the EF Core migrations feature for managing data model changes. Dans les didacticiels suivants, vous allez ajouter d’autres migrations au fil de la modification du modèle de données.In later tutorials, you'll add more migrations as you change the data model.

Dans ce didacticiel, vous avez effectué les actions suivantes :In this tutorial, you:

  • En savoir plus sur les migrationsLearn about migrations
  • Changer la chaîne de connexionChange the connection string
  • Créer une migration initialeCreate an initial migration
  • Examiner les méthodes Up et DownExamine Up and Down methods
  • En savoir plus sur la capture instantanée du modèle de donnéesLearn about the data model snapshot
  • Appliquer la migrationApply the migration

PrérequisPrerequisites

À propos des migrationsAbout migrations

Quand vous développez une nouvelle application, votre modèle de données change fréquemment et, chaque fois que le modèle change, il n’est plus en synchronisation avec la base de données.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. Vous avez démarré ce didacticiel en configurant Entity Framework pour créer la base de données si elle n’existait pas.You started these tutorials by configuring the Entity Framework to create the database if it doesn't exist. Ensuite, chaque fois que vous modifiez le modèle de données, en ajoutant, supprimant ou changeant des classes d’entité ou votre classe DbContext, vous pouvez supprimer la base de données : EF en crée alors une nouvelle qui correspond au modèle et l’alimente avec des données de test.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.

Cette méthode pour conserver la base de données en synchronisation avec le modèle de données fonctionne bien jusqu’au déploiement de l’application en production.This method of keeping the database in sync with the data model works well until you deploy the application to production. Quand l’application s’exécute en production, elle stocke généralement les données que vous voulez conserver, et vous ne voulez pas tout perdre chaque fois que vous apportez une modification, comme ajouter une nouvelle colonne.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. La fonctionnalité Migrations d’EF Core résout ce problème en permettant à EF de mettre à jour le schéma de base de données au lieu de créer une nouvelle base de données.The EF Core Migrations feature solves this problem by enabling EF to update the database schema instead of creating a new database.

Pour effectuer des migrations, vous pouvez utiliser la console du Gestionnaire de package ou l’interface de ligne de commande (CLI).To work with migrations, you can use the Package Manager Console (PMC) or the command-line interface (CLI). Ces didacticiels montrent comment utiliser des commandes CLI.These tutorials show how to use CLI commands. Vous trouverez des informations sur la console du Gestionnaire de package à la fin de ce didacticiel.Information about the PMC is at the end of this tutorial.

Changer la chaîne de connexionChange the connection string

Dans le fichier appsettings.json, remplacez le nom de la base de données dans la chaîne de connexion par ContosoUniversity2 ou par un autre nom que vous n’avez pas utilisé sur l’ordinateur que vous utilisez.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"
  },

Cette modification configure le projet de façon à ce que la première migration crée une nouvelle base de données.This change sets up the project so that the first migration will create a new database. Ce n’est pas obligatoire pour commencer à utiliser les migrations, mais vous verrez plus tard pourquoi c’est judicieux.This isn't required to get started with migrations, but you'll see later why it's a good idea.

Notes

Au lieu de changer le nom de la base de données, vous pouvez la supprimer.As an alternative to changing the database name, you can delete the database. Utilisez l’Explorateur d’objets SQL Server (SSOX) ou la commande CLI database drop :Use SQL Server Object Explorer (SSOX) or the database drop CLI command:

dotnet ef database drop

La section suivante explique comment exécuter des commandes CLI.The following section explains how to run CLI commands.

Créer une migration initialeCreate an initial migration

Enregistrez vos modifications et générez le projet.Save your changes and build the project. Ouvrez ensuite une fenêtre Commande et accédez au dossier du projet.Then open a command window and navigate to the project folder. Voici un moyen rapide pour le faire :Here's a quick way to do that:

  • Dans l’Explorateur de solutions, cliquez sur le projet et choisissez Ouvrir le dossier dans l’Explorateur de fichiers dans le menu contextuel.In Solution Explorer, right-click the project and choose Open Folder in File Explorer from the context menu.

    Élément de menu Ouvrir dans l’Explorateur de fichiers

  • Entrez « cmd » dans la barre d’adresses et appuyez sur Entrée.Enter "cmd" in the address bar and press Enter.

    Ouvrir une fenêtre Commande

Entrez la commande suivante dans la fenêtre Commande :Enter the following command in the command window:

dotnet ef migrations add InitialCreate

Vous voyez une sortie similaire à celle-ci dans la fenêtre Commande :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'

Notes

Si vous voyez un message d’erreur Aucun exécutable trouvé correspondant à la commande « dotnet-ef », consultez ce billet de blog pour résoudre ce problème.If you see an error message No executable found matching command "dotnet-ef", see this blog post for help troubleshooting.

Si vous voyez un message d’erreur « Impossible d’accéder au fichier... ContosoUniversity.dll, car il est utilisé par un autre processus. », recherchez l’icône IIS Express dans la barre d’état système de Windows, cliquez avec le bouton droit, puis cliquez sur ContosoUniversity > Arrêter le Site.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.

Examiner les méthodes Up et DownExamine Up and Down methods

Quand vous avez exécuté la commande migrations add, EF a généré le code qui crée la base de données à partir de zéro.When you executed the migrations add command, EF generated the code that will create the database from scratch. Ce code se trouve dans le dossier Migrations, dans le fichier nommé <horodatage>_InitialCreate.cs.This code is in the Migrations folder, in the file named <timestamp>_InitialCreate.cs. La méthode Up de la classe InitialCreate crée les tables de base de données qui correspondent aux jeux d’entités du modèle de données, et la méthode Down les supprime, comme indiqué dans l’exemple suivant.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
    }
}

La fonctionnalité Migrations appelle la méthode Up pour implémenter les modifications du modèle de données pour une migration.Migrations calls the Up method to implement the data model changes for a migration. Quand vous entrez une commande pour annuler la mise à jour, Migrations appelle la méthode Down.When you enter a command to roll back the update, Migrations calls the Down method.

Ce code est celui de la migration initiale qui a été créé quand vous avez entré la commande migrations add InitialCreate.This code is for the initial migration that was created when you entered the migrations add InitialCreate command. Le paramètre de nom de la migration (« InitialCreate » dans l’exemple) est utilisé comme nom de fichier ; vous pouvez le choisir librement.The migration name parameter ("InitialCreate" in the example) is used for the file name and can be whatever you want. Nous vous conseillons néanmoins de choisir un mot ou une expression qui résume ce qui est effectué dans la migration.It's best to choose a word or phrase that summarizes what is being done in the migration. Par exemple, vous pouvez nommer une migration ultérieure « AjouterTableDépartement ».For example, you might name a later migration "AddDepartmentTable".

Si vous avez créé la migration initiale alors que la base de données existait déjà, le code de création de la base de données est généré, mais il n’est pas nécessaire de l’exécuter, car la base de données correspond déjà au modèle de données.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. Quand vous déployez l’application sur un autre environnement où la base de données n’existe pas encore, ce code est exécuté pour créer votre base de données : il est donc judicieux de le tester au préalable.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. C’est la raison pour laquelle vous avez précédemment changé le nom de la base de données dans la chaîne de connexion : les migrations doivent pouvoir créer une base de données à partir de zéro.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.

Capture instantanée du modèle de donnéesThe data model snapshot

Migrations crée une capture instantanée du schéma de base de données actuel dans Migrations/SchoolContextModelSnapshot.cs.Migrations creates a snapshot of the current database schema in Migrations/SchoolContextModelSnapshot.cs. Quand vous ajoutez une migration, EF détermine ce qui a changé en comparant le modèle de données au fichier de capture instantanée.When you add a migration, EF determines what changed by comparing the data model to the snapshot file.

Lors de la suppression d’une migration, utilisez la commande dotnet ef migrations remove.When deleting a migration, use the dotnet ef migrations remove command. dotnet ef migrations remove supprime la migration et garantit que la capture instantanée est correctement réinitialisée.dotnet ef migrations remove deletes the migration and ensures the snapshot is correctly reset.

Pour plus d’informations sur l’utilisation du fichier de capture instantanée, consultez Migrations EF Core dans les environnements d’équipe.See EF Core Migrations in Team Environments for more information about how the snapshot file is used.

Appliquer la migrationApply the migration

Dans la fenêtre Commande, entrez la commande suivante pour créer la base de données et ses tables.In the command window, enter the following command to create the database and tables in it.

dotnet ef database update

La sortie de la commande est similaire à la commande migrations add, à ceci près que vous voyez des journaux pour les commandes SQL qui configurent la base de données.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. La plupart des journaux sont omis dans l’exemple de sortie suivant.Most of the logs are omitted in the following sample output. Si vous préférez ne pas voir ce niveau de détail dans les messages des journaux, vous pouvez changer le niveau de journalisation dans le fichier appsettings.Development.json.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. Pour plus d'informations, consultez Journalisation dans ASP.NET Core.For more information, see Journalisation dans 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.

Utilisez l’Explorateur d’objets SQL Server pour inspecter la base de données, comme vous l’avez fait dans le premier didacticiel.Use SQL Server Object Explorer to inspect the database as you did in the first tutorial. Vous pouvez noter l’ajout d’une table __EFMigrationsHistory, qui fait le suivi des migrations qui ont été appliquées à la base de données.You'll notice the addition of an __EFMigrationsHistory table that keeps track of which migrations have been applied to the database. Visualisez les données de cette table : vous y voyez une ligne pour la première migration.View the data in that table and you'll see one row for the first migration. (Le dernier journal dans l’exemple de sortie CLI précédent montre l’instruction INSERT qui crée cette ligne.)(The last log in the preceding CLI output example shows the INSERT statement that creates this row.)

Exécutez l’application pour vérifier que tout fonctionne toujours comme avant.Run the application to verify that everything still works the same as before.

Page d’index des étudiants

Comparer l’interface CLI et PMCCompare CLI and PMC

Les outils EF pour la gestion des migrations sont disponibles à partir de commandes CLI .NET Core ou d’applets de commande PowerShell dans la fenêtre Console du Gestionnaire de package de Visual Studio.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. Ce didacticiel montre comment utiliser l’interface CLI, mais vous pouvez utiliser la console du Gestionnaire de package si vous préférez.This tutorial shows how to use the CLI, but you can use the PMC if you prefer.

Les commandes EF pour la console du Gestionnaire de package se trouvent dans le package Microsoft.EntityFrameworkCore.Tools.The EF commands for the PMC commands are in the Microsoft.EntityFrameworkCore.Tools package. Ce package étant inclus dans le métapackage Microsoft.AspNetCore.App, vous n’avez pas besoin d’ajouter une référence de package si votre application en comporte une pour Microsoft.AspNetCore.App.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.

Important : Il ne s’agit pas du même package que celui que vous installez pour l’interface CLI en modifiant le fichier .csproj.Important: This isn't the same package as the one you install for the CLI by editing the .csproj file. Le nom de celui-ci se termine par Tools, contrairement au nom du package CLI qui se termine par Tools.DotNet.The name of this one ends in Tools, unlike the CLI package name which ends in Tools.DotNet.

Pour plus d’informations sur les commandes CLI, consultez Interface CLI .NET Core.For more information about the CLI commands, see .NET Core CLI.

Pour plus d’informations sur les commandes de la console du Gestionnaire de package, consultez Console du Gestionnaire de package (Visual Studio).For more information about the PMC commands, see Package Manager Console (Visual Studio).

Obtenir le codeGet the code

Télécharger ou afficher l’application complète.Download or view the completed application.

Étape suivanteNext step

Dans ce didacticiel, vous avez effectué les actions suivantes :In this tutorial, you:

  • Migrations découvertesLearned about migrations
  • Packages NuGet de migration découvertsLearned about NuGet migration packages
  • Chaîne de connexion modifiéeChanged the connection string
  • Migration initiale crééeCreated an initial migration
  • Méthodes Up et Down examinéesExamined Up and Down methods
  • Capture instantanée du modèle de données découverteLearned about the data model snapshot
  • Migration appliquéeApplied the migration

Passez au tutoriel suivant pour aborder des sujets plus avancés sur le développement du modèle de données.Advance to the next tutorial to begin looking at more advanced topics about expanding the data model. Au cour de ce processus, vous allez créer et appliquer d’autres migrations.Along the way you'll create and apply additional migrations.