Entity Framework Migrations

Entity Framework (EF) Migrations is a powerful feature that allows you to evolve your database schema over time as your application's model changes.

What are Migrations?

Migrations are a series of C# classes that represent changes to your database schema. When you make changes to your EF Core model (like adding a new entity, property, or relationship), EF Core can generate a migration that describes how to update your database to match that new model. This ensures your database schema stays synchronized with your application code.

Key Concepts

Migrations: C# classes that contain the code to apply schema changes (Up() method) and to revert them (Down() method).
DbContext: Your main class for interacting with the database. Migrations are tied to your DbContext.
Add-Migration (Package Manager Console): Command to scaffold a new migration based on changes in your model.
dotnet ef migrations add (CLI): Equivalent command for .NET CLI users.
Update-Database (Package Manager Console): Command to apply pending migrations to your database.
dotnet ef database update (CLI): Equivalent command for .NET CLI users.

Common Workflow

Here's the typical process for using EF Core Migrations:

Make Model Changes: Modify your EF Core entity classes or DbContext configuration. For example, add a new property to an existing entity:


public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public string Description { get; set; } // New property
}

Add a Migration: Scaffold a new migration using the Package Manager Console or the .NET CLI.

Package Manager Console (Visual Studio)

Ensure you have the Microsoft.EntityFrameworkCore.Tools NuGet package installed.
Add-Migration AddProductDescription

.NET CLI

Ensure you have the Microsoft.EntityFrameworkCore.Design NuGet package installed.
dotnet ef migrations add AddProductDescription

This command generates two files in your Migrations folder:
- A migration file (e.g., YYYYMMDDHHMMSS_AddProductDescription.cs) containing the Up() and Down() methods.
- A snapshot file (YourDbContextModelSnapshot.cs) representing the current state of your model.

Review the Migration: Open the generated migration file and inspect the Up() method. EF Core is usually good at generating schema changes, but you might need to manually adjust it, especially for complex scenarios.


public partial class AddProductDescription : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.AddColumn<string>(
            name: "Description",
            table: "Products",
            type: "nvarchar(max)",
            nullable: true); // Note: nullable might depend on your configuration
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropColumn(
            name: "Description",
            table: "Products");
    }
}

Apply the Migration: Update your database to incorporate the changes defined in the migration.

Package Manager Console (Visual Studio)
Update-Database

.NET CLI
dotnet ef database update

This command will execute the Up() method of all pending migrations.

Important: Always review your generated migrations before applying them, especially in production environments. For production deployments, consider using tools like EF Core Power Tools or custom scripts to manage migration application.

Advanced Scenarios

Data Annotations vs. Fluent API: Migrations can be generated based on either Data Annotations or the Fluent API configuration in your DbContext.
Complex Transformations: For complex data transformations or schema changes that EF Core can't automatically infer, you can write custom SQL using migrationBuilder.Sql() within your migration's Up() and Down() methods.
Seeding Data: You can seed initial data into your database using migrations, often in the Up() method of an early migration.
Reverting Migrations: If you need to undo a migration, you can use commands like Update-Database -TargetMigration InitialCreate (to go back to a specific migration) or delete migration files and then re-run Update-Database (use with extreme caution!).

Learn More on Microsoft Docs