MigrationsMigrations

Les migrations permettent d’appliquer de façon incrémentielle des modifications de schéma à la base de données pour qu’elle demeure synchronisée avec votre modèle EF Core tout en conservant les données existantes dans la base de données.Migrations provide a way to incrementally apply schema changes to the database to keep it in sync with your EF Core model while preserving existing data in the database.

Création de la base de donnéesCreating the database

Une fois que vous avez défini votre modèle initial, il est temps de créer la base de données.After you've defined your initial model, it's time to create the database. Pour ce faire, ajoutez une migration initiale.To do this, add an initial migration. Installez les outils EF Core et exécutez la commande appropriée.Install the EF Core Tools and run the appropriate command.

Add-Migration InitialCreate
dotnet ef migrations add InitialCreate

Trois fichiers sont ajoutés à votre projet sous le répertoire Migrations :Three files are added to your project under the Migrations directory:

  • 00000000000000_InitialCreate.cs : fichier principal des migrations.00000000000000_InitialCreate.cs--The main migrations file. Contient les opérations nécessaires à l’application de la migration (dans Up()) et à sa restauration (dans Down()).Contains the operations necessary to apply the migration (in Up()) and to revert it (in Down()).
  • 00000000000000_InitialCreate.Designer.cs : fichier de métadonnées des migrations.00000000000000_InitialCreate.Designer.cs--The migrations metadata file. Contient des informations utilisées par EF.Contains information used by EF.
  • MyContextModelSnapshot.cs : instantané de votre modèle actuel.MyContextModelSnapshot.cs--A snapshot of your current model. Permet de déterminer ce qui a changé pendant l’ajout de la migration suivante.Used to determine what changed when adding the next migration.

L’horodatage dans le nom des fichiers permet de conserver ces derniers dans l’ordre chronologique et de voir ainsi la progression des modifications.The timestamp in the filename helps keep them ordered chronologically so you can see the progression of changes.

Conseil

Vous êtes libre de déplacer les fichiers Migrations et de changer leur espace de noms.You are free to move Migrations files and change their namespace. Les migrations sont créées en tant que sœurs de la dernière migration.New migrations are created as siblings of the last migration.

Ensuite, appliquez la migration à la base de données pour créer le schéma.Next, apply the migration to the database to create the schema.

Update-Database
dotnet ef database update

Ajout d’une autre migrationAdding another migration

Une fois votre modèle EF Core modifié, le schéma de base de données n’est plus synchronisé. Pour le mettre à jour, ajoutez une autre migration.After making changes to your EF Core model, the database schema will be out of sync. To bring it up to date, add another migration. Le nom de la migration peut être utilisé comme un message de validation dans un système de gestion de versions.The migration name can be used like a commit message in a version control system. Par exemple, si j’ai apporté des modifications pour enregistrer des avis de clients sur des produits, je peux choisir quelque chose comme AddProductReviews.For example, if I made changes to save customer reviews of products, I might choose something like AddProductReviews.

Add-Migration AddProductReviews
dotnet ef migrations add AddProductReviews

Une fois la migration structurée, vous devez vérifier sa précision et ajouter toutes les opérations supplémentaires nécessaires à son application.Once the migration is scaffolded, you should review it for accuracy and add any additional operations required to apply it correctly. Par exemple, la migration peut contenir les opérations suivantes :For example, your migration might contain the following operations:

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

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

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

Bien que ces opérations rendent le schéma de base de données compatible, elles ne conservent pas les noms de client existants.While these operations make the database schema compatible, they don't preserve the existing customer names. Pour l’améliorer, réécrivez la migration comme suit.To make it better, rewrite it as follows.

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

migrationBuilder.Sql(
@"
    UPDATE Customer
    SET Name = FirstName + ' ' + LastName;
");

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

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

Conseil

L’ajout d’une nouvelle migration émet un avertissement si la structuration d’une opération risque d’entraîner une perte de données (telle que la suppression d’une colonne).Adding a new migration warns when an operation is scaffolded that may result in data loss (like dropping a column). Veillez à vérifier tout particulièrement la précision de ces migrations.Be sure to especially review these migrations for accuracy.

Appliquez la migration à la base de données à l’aide de la commande appropriée.Apply the migration to the database using the appropriate command.

Update-Database
dotnet ef database update

Suppression d’une migrationRemoving a migration

Parfois, vous ajoutez une migration et réalisez que vous devez apporter des modifications supplémentaires à votre modèle EF Core avant de l’appliquer.Sometimes you add a migration and realize you need to make additional changes to your EF Core model before applying it. Pour supprimer la dernière migration, utilisez cette commande.To remove the last migration, use this command.

Remove-Migration
dotnet ef migrations remove

Après l’avoir supprimée, vous pouvez apporter les modifications supplémentaires au modèle et la rajouter.After removing it, you can make the additional model changes and add it again.

Restauration d’une migrationReverting a migration

Si vous avez déjà appliqué une migration (ou plusieurs migrations) à la base de données, mais que vous devez la restaurer, vous pouvez utiliser la même commande que celle servant à appliquer des migrations, mais en spécifiant le nom de la migration à restaurer.If you already applied a migration (or several migrations) to the database but need to revert it, you can use the same command to apply migrations, but specify the name of the migration you want to roll back to.

Update-Database LastGoodMigration
dotnet ef database update LastGoodMigration

Migrations videsEmpty migrations

Il est parfois utile d’ajouter une migration sans apporter de modification au modèle.Sometimes it's useful to add a migration without making any model changes. Dans ce cas, l’ajout d’une nouvelle migration crée une migration vide.In this case, adding a new migration creates an empty one. Vous pouvez personnaliser cette migration pour effectuer des opérations qui ne sont pas directement liées au modèle EF Core.You can customize this migration to perform operations that don't directly relate to the EF Core model. Voici quelques exemples de ce que vous pouvez gérer de cette façon :Some things you might want to manage this way are:

  • Recherche en texte intégralFull-Text Search
  • FonctionsFunctions
  • Procédures stockéesStored procedures
  • DéclencheursTriggers
  • AffichagesViews
  • Etc.etc.

Génération d’un script SQLGenerating a SQL script

Quand vous déboguez vos migrations ou que vous les déployez sur une base de données de production, il est utile de générer un script SQL.When debugging your migrations or deploying them to a production database, it's useful to generate a SQL script. Vous pouvez ensuite revoir le script et l’affiner en fonction des besoins d’une base de données de production.The script can then be further reviewed for accuracy and tuned to fit the needs of a production database. Vous pouvez également utiliser le script conjointement avec une technologie de déploiement.The script can also be used in conjunction with a deployment technology. La commande de base est la suivante.The basic command is as follows.

Script-Migration
dotnet ef migrations script

Il existe plusieurs options pour cette commande.There are several options to this command.

La migration from doit être la dernière migration appliquée à la base de données avant l’exécution du script.The from migration should be the last migration applied to the database before running the script. Si aucune migration n’a été appliquée, spécifiez 0 (il s’agit de la valeur par défaut).If no migrations have been applied, specify 0 (this is the default).

La migration to est la dernière migration à appliquer à la base de données après l’exécution du script.The to migration is the last migration that will be applied to the database after running the script. Par défaut, il s’agit de la dernière migration dans votre projet.This defaults to the last migration in your project.

Un script idempotent peut également être généré.An idempotent script can optionally be generated. Ce script n’applique les migrations que si elles n’ont pas déjà été appliquées à la base de données.This script only applies migrations if they haven't already been applied to the database. Cela est utile si vous ne savez pas exactement ce que la dernière migration a appliqué à la base de données ou si vous effectuez un déploiement sur plusieurs bases de données pouvant chacune être liée à une migration différente.This is useful if you don't exactly know what the last migration applied to the database was or if you are deploying to multiple databases that may each be at a different migration.

Application de migrations au moment de l’exécutionApplying migrations at runtime

Certaines applications sont susceptibles d’appliquer des migrations au moment de l’exécution (au démarrage ou à la première exécution).Some apps may want to apply migrations at runtime during startup or first run. Ces opérations nécessitent l’utilisation de la méthode Migrate().Do this using the Migrate() method.

Attention, cette approche ne s’adresse pas à tout un chacun.Caution, this approach isn't for everyone. Bien qu’elle soit idéale pour les applications avec une base de données locale, la plupart des applications nécessitent une stratégie de déploiement plus robuste, telle que la génération de scripts SQL.While it's great for apps with a local database, most applications will require more robust deployment strategy like generating SQL scripts.

myDbContext.Database.Migrate();

Avertissement

N’appelez pas EnsureCreated() avant Migrate().Don't call EnsureCreated() before Migrate(). EnsureCreated() ignore Migrations pour créer le schéma, ce qui entraîne l’échec de Migrate().EnsureCreated() bypasses Migrations to create the schema, which causes Migrate() to fail.

Note

Cette méthode s’appuie sur le service IMigrator, qui peut être utilisé pour des scénarios plus avancés.This method builds on top of the IMigrator service, which can be used for more advanced scenarios. Utilisez DbContext.GetService<IMigrator>() pour y accéder.Use DbContext.GetService<IMigrator>() to access it.