EF Core 9 升级中 Cosmos DB 向后兼容性问题解析

背景介绍

在将 Entity Framework Core 从版本 8 升级到版本 9 的过程中，使用 Cosmos DB 作为数据存储的开发人员可能会遇到一个特定的兼容性问题。这个问题表现为当尝试访问旧版本创建的数据库时，系统会抛出错误信息："The value 'dbs//colls/Identity' specified for query '$resolveFor' is invalid"。

问题本质

这个问题的根源在于 EF Core 9 对 Cosmos DB 提供程序进行了两项重大变更：

1. JSON ID 中的鉴别器处理方式变更：EF Core 9 默认使用 $type 属性作为类型鉴别器，而不再使用旧版的 Discriminator 字段。

2. 索引检测行为变更：新版本会对实体中的索引抛出错误，这要求开发者完全重写基类的 OnModelCreating 方法。

解决方案实现

为了保持向后兼容性，开发者需要在 OnModelCreating 方法中进行以下配置：

protected override void OnModelCreating(ModelBuilder builder)
{
    // 启用旧版JSON ID鉴别器处理方式
    builder.HasDiscriminatorInJsonIds();
    
    // 不调用基类的OnModelCreating方法
    // base.OnModelCreating(builder);
    
    // 其他模型配置...
    
    // 如果需要完全兼容旧版鉴别器字段名
    if (_backwardCompatibility)
    {
        builder.HasEmbeddedDiscriminatorName("Discriminator");
    }
}

常见陷阱与解决方案

在实际应用中，开发者可能会遇到以下两个典型问题：

1. 模型缓存问题：如果在测试或应用初始化时先创建了不兼容的模型实例，后续即使设置了兼容性标志，系统仍会使用缓存的错误模型。解决方案是确保首次创建模型时就设置正确的兼容性参数。

2. 数据库名称不一致：在测试环境中，如果实际使用的数据库名称与代码中指定的不一致，会导致连接错误。需要仔细检查数据库名称的传递逻辑，确保一致性。

数据格式对比

新旧版本的数据存储格式有明显差异：

EF Core 8 及以下版本格式：

{
    "Id": "363e94ec-2745-40da-8220-fd0da4bc9a4a",
    "Discriminator": "IdentityUser",
    // 其他字段...
}

EF Core 9 新格式：

{
    "Id": "d96decd1-4efa-4c77-9a24-2424a1d98104",
    "$type": "IdentityUser",
    // 其他字段...
}

最佳实践建议

1. 在升级前，充分测试兼容性设置，确保现有数据可访问。

2. 考虑数据迁移策略，可以将旧数据批量转换为新格式。

3. 在团队内部明确记录兼容性设置，避免后续开发人员无意中修改关键配置。

4. 对于长期维护的项目，建议逐步迁移到新格式，而不是长期保持兼容模式。

通过正确理解和应用这些兼容性配置，开发者可以顺利完成 EF Core 9 的升级，同时确保现有 Cosmos DB 数据的可访问性。