EF Core 9.0 迁移中的 PendingModelChangesWarning 异常解析

问题背景

在从 .NET 8 升级到 .NET 9 的过程中，许多开发者在使用 Entity Framework Core 9.0 时遇到了一个特殊的异常：PendingModelChangesWarning。这个异常会在调用 Database.Migrate() 方法时抛出，提示数据库上下文存在待处理的模型变更，需要先添加新的迁移。

异常现象

典型的异常信息如下：

System.InvalidOperationException: An error was generated for warning 'Microsoft.EntityFrameworkCore.Migrations.PendingModelChangesWarning': The model for context 'WasDbContext' has pending changes. Add a new migration before updating the database.

这个异常在 .NET 8 及之前版本中不会出现，但在升级到 .NET 9 后开始频繁发生，即使开发者确认没有实际的模型变更。

问题原因

经过深入分析，这个问题主要有以下几个潜在原因：

1. EF Core 9.0 行为变更：EF Core 9.0 对模型变更检测机制进行了改进，现在会更加严格地检查模型与数据库之间的差异。

2. 设计时与运行时上下文配置不一致：当使用 IDesignTimeDbContextFactory 时，如果设计时工厂没有包含与运行时相同的配置（如 ASP.NET Core Identity 的配置），会导致模型检测不一致。

3. 数据库手动修改：如果直接在数据库中手动修改了某些结构（如索引），而迁移历史中没有相应记录，也会被检测为模型变更。

4. 环境特定配置：某些配置可能在不同环境中表现不同，导致模型检测结果不一致。

解决方案

1. 创建新的迁移

最简单的解决方案是创建一个新的空迁移：

dotnet ef migrations add UpdateForNet9

即使没有实际模型变更，这也能使迁移历史与当前模型状态同步。

2. 配置警告行为

如果确认没有实际模型变更，可以选择将警告降级为日志而非异常：

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.ConfigureWarnings(warnings => 
        warnings.Log(RelationalEventId.PendingModelChangesWarning));
}

3. 确保设计时配置一致性

对于使用 ASP.NET Core Identity 的项目，确保设计时工厂包含所有必要的配置：

public class DatabaseContextFactory : IDesignTimeDbContextFactory<IssueReproDb>
{
    public IssueReproDb CreateDbContext(string[] args)
    {
        var services = new ServiceCollection();
        services
            .AddDbContext<IssueReproDb>(options => options.UseNpgsql("Data Source=blog.db"))
            .AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<IssueReproDb>();

        var serviceProvider = services.BuildServiceProvider();
        var scope = serviceProvider.CreateScope();
        return scope.ServiceProvider.GetRequiredService<IssueReproDb>();
    }
}

4. 检查环境特定配置

使用 IMigrationsModelDiffer 诊断实际差异：

var differences = _migrationsModelDiffer.GetDifferences(
    _modelRuntimeInitializer.Initialize(_migrationsAssembly.ModelSnapshot.Model).GetRelationalModel(),
    _designTimeModel.Model.GetRelationalModel());

技术细节

EF Core 9.0 引入这一变更的主要目的是防止潜在的运行时错误。在之前版本中，模型与数据库不同步可能导致难以追踪的问题。现在，EF Core 会主动检测并提醒开发者这些不一致。

值得注意的是，ASP.NET Core Identity 在不同使用场景下（直接继承 IdentityDbContext 与通过 AddIdentity 配置）会使用不同的模型版本，这也是导致一些差异的原因。

最佳实践

1. 在升级到 EF Core 9.0 后，即使没有业务需求，也建议创建一个新的迁移。

2. 确保所有环境中的配置一致，特别是设计时与运行时的配置。

3. 避免直接手动修改数据库结构，所有变更应通过迁移完成。

4. 对于复杂的项目，考虑实现更完善的设计时上下文工厂，确保它能准确反映运行时配置。

通过理解这些变更背后的原理并采取适当的措施，开发者可以顺利过渡到 EF Core 9.0，同时利用其更严格的模型验证机制来提高应用程序的可靠性。