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

问题背景

在将项目从 .NET 8 升级到 .NET 9 后，许多开发者遇到了一个关于 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.

根本原因

在 EntityFramework Core 9.0 中，团队引入了一个重要的变更：将原本的警告级别提示升级为了异常抛出。这一变更的目的是为了更早地捕获模型与数据库不匹配的情况，避免潜在的数据一致性问题。

导致这一异常的具体原因可能有以下几种：

1. 模型与快照不匹配：自上次迁移以来，实体模型发生了变化但未生成新的迁移
2. 环境差异：不同环境中数据库的实际结构与模型快照存在差异
3. ASP.NET Identity 配置差异：使用 Identity 时，设计时上下文与运行时上下文的配置不一致
4. 遗留配置开关：如 Npgsql 的 EnableLegacyTimestampBehavior 等遗留配置影响模型构建

解决方案

1. 创建新的迁移

最直接的解决方案是创建一个新的迁移：

dotnet ef migrations add YourMigrationName

2. 配置警告级别

如果确定不需要处理这些变更，可以降级为警告而非异常：

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

3. 处理 ASP.NET Identity 的特殊情况

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

public class DatabaseContextFactory : IDesignTimeDbContextFactory<YourDbContext>
{
    public YourDbContext CreateDbContext(string[] args)
    {
        var services = new ServiceCollection();
        services
            .AddDbContext<YourDbContext>(/* 配置 */)
            .AddDefaultIdentity<IdentityUser>(/* 配置 */)
            .AddEntityFrameworkStores<YourDbContext>();

        return services.BuildServiceProvider()
            .GetRequiredService<YourDbContext>();
    }
}

4. 检查环境一致性

使用 IMigrationsModelDiffer 诊断具体差异：

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

最佳实践

1. 升级后首先生成迁移：即使没有明显变更，也建议在主要版本升级后生成迁移
2. 统一环境配置：确保开发、测试和生产环境使用相同的数据库配置
3. 完整的设计时配置：设计时上下文工厂应包含所有运行时配置
4. 逐步验证：在升级过程中分阶段验证数据库变更

总结

EntityFramework Core 9.0 的这一变更虽然带来了一些升级挑战，但从长远看有助于提高数据一致性。开发者应理解其背后的设计意图，并根据项目实际情况选择合适的处理方式。对于复杂项目，建议在升级前充分测试数据库迁移流程，确保平滑过渡。