EF Core 9.0 迁移脚手架编程接口的重大变更与解决方案

问题背景

在升级到 Entity Framework Core 9.0.0 版本后，许多开发者在使用编程方式生成数据库迁移时遇到了一个关键性问题。当尝试通过 IMigrationsScaffolder 接口的 ScaffoldMigration 方法生成迁移文件时，系统会抛出 InvalidOperationException 异常，提示"Metadata changes are not allowed when the model has been marked as read-only"。

问题本质

这个问题的根源在于 EF Core 9.0 对模型元数据处理的内部机制进行了调整。在之前的版本中，模型元数据可以在生成迁移时被修改，但在 9.0 版本中，一旦模型被标记为只读状态，任何尝试修改元数据的操作都会导致异常。

典型场景分析

开发者通常会遇到这个问题在以下两种场景中：

1. 初始迁移生成：当数据库尚不存在时，尝试生成第一个迁移
2. 后续模型变更：在已有数据库和迁移历史的情况下，对模型进行修改后生成新的迁移

特别值得注意的是，这个问题在使用 DbContext.Database.GetPendingMigrations() 或 DbContext.Database.Migrate() 方法后尤为明显，因为这些操作会将模型标记为只读状态。

解决方案

对于 EF Core 9.0.4 及以上版本，微软已经发布了修复补丁。开发者可以采取以下措施：

1. 升级到最新版本：确保使用 EF Core 9.0.4 或更高版本
2. 调整项目配置：移除 .csproj 文件中可能导致设计时组件不可用的 PrivateAssets 设置
3. 代码调整：避免在生成迁移前调用任何迁移相关API

最佳实践建议

对于需要编程方式生成迁移的场景，推荐以下实现模式：

// 检查数据库是否存在或模型是否有变更
if (!await relationalDatabaseCreator.ExistsAsync() || 
    dbContext.Database.HasPendingModelChanges())
{
    // 配置设计时服务
    var services = new ServiceCollection()
        .AddEntityFrameworkDesignTimeServices()
        .AddDbContextDesignTimeServices(dbContext);
    
    // 添加特定数据库提供程序的设计时服务
    var designTimeServices = new SqlServerDesignTimeServices();
    designTimeServices.ConfigureDesignTimeServices(services);

    // 构建服务并获取脚手架实例
    var scaffolder = services.BuildServiceProvider()
        .GetRequiredService<IMigrationsScaffolder>();

    // 生成迁移文件
    var migration = scaffolder.ScaffoldMigration(
        $"Migration-{DateTime.Now:yyyyMMddHHmmss}",
        "Your.NameSpace",
        "Migrations");
    
    // 保存生成的迁移文件
    // ...
}

迁移生成策略优化

在 EF Core 9.0 中，迁移生成的内部逻辑有所变化，开发者需要注意：

1. 模型快照处理：确保模型快照文件存在且有效
2. 迁移顺序：避免在生成新迁移前执行任何可能锁定模型的操作
3. 版本兼容性：检查所有相关包版本的一致性

总结

EF Core 9.0 在模型元数据处理上的这一变更虽然带来了短期内的兼容性问题，但从长远来看提高了框架的稳定性和可预测性。开发者通过升级到最新补丁版本并遵循推荐的最佳实践，可以顺利过渡到新版本，同时获得更好的开发体验。

对于复杂的应用场景，特别是那些需要高度自动化迁移管理的系统，建议在升级前充分测试迁移生成逻辑，确保所有边缘情况都能正确处理。