Tutoriel : Partie 5, appliquer des migrations à l’exemple Contoso University

Dans ce tutoriel, vous utilisez la fonctionnalité de migrations EF Core pour gérer les modifications du modèle de données. Dans les didacticiels suivants, vous allez ajouter d’autres migrations au fil de la modification du modèle de données.

Dans ce didacticiel, vous avez effectué les actions suivantes :

Prérequis

• Tri, filtrage et pagination

À propos des 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. Vous avez démarré ce didacticiel en configurant Entity Framework pour créer la base de données si elle n’existait pas. 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.

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. 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. La fonctionnalité de migrations 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.

Pour effectuer des migrations, vous pouvez utiliser la console du gestionnaire de package (PMC) ou l’interface de ligne de commande (CLI). Ces didacticiels montrent comment utiliser des commandes CLI. Vous trouverez des informations sur la console du Gestionnaire de package à la fin de ce didacticiel.

Supprimer la base de données

Installez les outils EF Core en tant qu’outil global et supprimez la base de données :

dotnet tool install --global dotnet-ef
dotnet ef database drop

La section suivante explique comment exécuter des commandes CLI.

Créer une migration initiale

Enregistrez vos modifications et générez le projet. Ouvrez ensuite une fenêtre Commande et accédez au dossier du projet. Voici un moyen rapide pour le faire :

• Dans l’Explorateur de solutions, cliquez sur le projet et choisissez Ouvrir le dossier dans l’Explorateur de fichiers dans le menu contextuel.

  

• Entrez « cmd » dans la barre d’adresses et appuyez sur Entrée.

  

Entrez la commande suivante dans la fenêtre Commande :

dotnet ef migrations add InitialCreate

Dans les commandes précédentes, une sortie similaire à ce qui suit s’affiche :

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

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>.

Examiner les méthodes Up et Down

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. Ce code se trouve dans le dossier Migrations, dans le fichier nommé <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.

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. Quand vous entrez une commande pour annuler la mise à jour, Migrations appelle la méthode Down.

Ce code est celui de la migration initiale qui a été créé quand vous avez entré la commande migrations add InitialCreate. Le paramètre de nom de la migration (« InitialCreate » dans l’exemple) est utilisé comme nom de fichier ; vous pouvez le choisir librement. Nous vous conseillons néanmoins de choisir un mot ou une expression qui résume ce qui est effectué dans la migration. Par exemple, vous pouvez nommer une migration ultérieure « AjouterTableDépartement ».

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. 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. C’est la raison pour laquelle vous avez précédemment annulé la base de données : les migrations doivent pouvoir créer une base de données à partir de zéro.

Capture instantanée du modèle de données

Migrations crée une capture instantanée du schéma de base de données actuel dans 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.

Utilisez la commande dotnet ef migrations remove pour supprimer une migration. dotnet ef migrations remove supprime la migration et garantit que la capture instantanée est correctement réinitialisée. En cas d’échec de dotnet ef migrations remove, utilisez dotnet ef migrations remove -v pour obtenir plus d’informations sur l’échec.

Pour plus d’informations sur l’utilisation du fichier de capture instantanée, consultez Migrations EF Core dans les environnements d’équipe.

Appliquer la migration

Dans la fenêtre Commande, entrez la commande suivante pour créer la base de données et ses tables.

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. La plupart des journaux sont omis dans l’exemple de sortie suivant. 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. Pour plus d’informations, consultez Journalisation dans .NET Core et ASP.NET Core.

info: Microsoft.EntityFrameworkCore.Infrastructure[10403]
      Entity Framework Core 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'5.0-rtm');
Done.

Utilisez l’Explorateur d’objets SQL Server pour inspecter la base de données, comme vous l’avez fait dans le premier didacticiel. 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. Visualisez les données de cette table : vous y voyez une ligne pour la première migration. (Le dernier journal dans l’exemple de sortie CLI précédent montre l’instruction INSERT qui crée cette ligne.)

Exécutez l’application pour vérifier que tout fonctionne toujours comme avant.

Comparer l’interface CLI et PMC

Les outils EF pour la gestion des migrations sont disponibles à partir de commandes d’interface CLI .NET ou d’applets de commande PowerShell dans la fenêtre Console du Gestionnaire de package de Visual Studio. Ce didacticiel montre comment utiliser l’interface CLI, mais vous pouvez utiliser la console du Gestionnaire de package si vous préférez.

Les commandes EF pour la console du Gestionnaire de package se trouvent dans le package Microsoft.EntityFrameworkCore.Tools. 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.

Important : il ne s’agit pas du même package que celui que vous installez pour l’interface CLI en modifiant le fichier .csproj. Le nom de celui-ci se termine par Tools, contrairement au nom du package CLI qui se termine par Tools.DotNet.

Pour plus d’informations sur les commandes d’interface CLI, consultez Interface CLI .NET.

Pour plus d’informations sur les commandes de la console du Gestionnaire de package, consultez Console du Gestionnaire de package (Visual Studio).

Obtenir le code

Télécharger ou afficher l’application complète.

Étape suivante

Passez au tutoriel suivant pour aborder des sujets plus avancés sur le développement du modèle de données. Au cours de ce processus, vous allez créer et appliquer d’autres migrations.