MigrationsMigrations

Un modèle de données change au cours du développement et perd sa synchronisation avec la base de données.A data model changes during development and gets out of sync with the database. Vous pouvez supprimer la base de données et laisser EF en créer une qui correspond au modèle, mais cette procédure entraîne la perte de données.You can drop the database and let EF create a new one that matches the model, but this procedure results in the loss of data. La fonctionnalité de migration dans EF Core permet de mettre à jour de manière incrémentielle le schéma de la base de données pour qu’il reste synchronisé avec le modèle de données de l’application tout en conservant les données existantes dans la base de données.The migrations feature in EF Core provides a way to incrementally update the database schema to keep it in sync with the application's data model while preserving existing data in the database.

Les migrations incluent des outils en ligne de commande et des API qui aident à effectuer les tâches suivantes :Migrations includes command-line tools and APIs that help with the following tasks:

Installer les outilsInstall the tools

Installez les outils en ligne de commande :Install the command-line tools:

Créer une migrationCreate a migration

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 ajouter une migration initiale, exécutez la commande suivante.To add an initial migration, run the following 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.

Mettre à jour la base de donnéesUpdate the database

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

Personnaliser le code de migrationCustomize migration code

Une fois votre modèle EF Core modifié, le schéma de base de données risque de ne plus être synchronisé. Pour le mettre à jour, ajoutez une autre migration.After making changes to your EF Core model, the database schema might 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, vous pouvez choisir un nom tel que AjouterÉvaluationsProduit si la modification est une nouvelle classe d’entité pour les évaluations.For example, you might choose a name like AddProductReviews if the change is a new entity class for reviews.

Add-Migration AddProductReviews
dotnet ef migrations add AddProductReviews

Une fois que la migration a été structurée (que du code a été généré pour elle), vérifiez si le code est exact et ajoutez, supprimez ou modifiez toutes les opérations nécessaires pour pouvoir l’appliquer correctement.Once the migration is scaffolded (code generated for it), review the code for accuracy and add, remove or modify any operations required to apply it correctly.

Par exemple, une migration peut contenir les opérations suivantes :For example, a 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

Le processus de structuration de migration vous avertit quand une opération peut entraîner une perte de données (par exemple la suppression d’une colonne).The migration scaffolding process warns when an operation might result in data loss (like dropping a column). Si cet avertissement s’affiche, veillez particulièrement à examiner si le code de migration est exact.If you see that warning, be especially sure to review the migrations code 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

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 des fichiers de code avec des classes vides.In this case, adding a new migration creates code files with empty classes. 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

Supprimer une migrationRemove 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 avoir supprimé la migration, vous pouvez apporter les modifications supplémentaires au modèle et la rajouter.After removing the migration, you can make the additional model changes and add it again.

Rétablir une migrationRevert 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

Générer des scripts SQLGenerate SQL scripts

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.

Appliquer des migrations au moment de l’exécutionApply 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.

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.

myDbContext.Database.Migrate();

Avertissement

  • Cette approche ne s’adresse pas à tout un chacun.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.
  • 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.

Étapes suivantesNext steps

Pour plus d'informations, consultez Informations de référence sur les outils Entity Framework Core - EF Core.For more information, see Informations de référence sur les outils Entity Framework Core - EF Core.