EF Core 9.0中Cosmos DB的ID属性映射变更解析

背景介绍

在Entity Framework Core 9.0版本中，针对Cosmos DB提供程序进行了重要的设计变更，特别是关于实体ID属性的映射方式。这一变更影响了现有应用程序的数据存储结构，需要开发者理解其原理并进行相应的调整。

变更内容

在EF Core 8.x及更早版本中，当使用Cosmos DB提供程序时，实体类中的Id属性会被映射为两个不同的JSON属性：

• 大写的Id（与.NET属性名一致）
• 小写的id（Cosmos DB标准格式）

这种双重映射导致了不必要的数据冗余，因为实际上这两个属性存储的是相同的值。

EF Core 9.0对此进行了优化，现在默认情况下：

• 实体类的Id属性仅映射为小写的idJSON属性
• 不再生成大写的Id属性

变更影响

这一变更主要影响以下场景：

1. 现有应用程序升级到EF Core 9.0后，新创建的容器将使用小写的id作为分区键路径
2. 如果现有容器使用大写的Id作为分区键路径，会导致兼容性问题
3. 查询和更新操作不受影响，因为EF Core会正确处理属性映射

解决方案

对于新项目，建议直接使用9.0的默认行为，这是更符合Cosmos DB标准的设计。

对于需要保持向后兼容的现有项目，EF Core 9.0提供了两种解决方案：

1. 使用HasDefaultId()方法： 在模型配置中显式调用此方法可以恢复8.x版本的行为，同时生成Id和id两个属性。

modelBuilder.Entity<Gateway>()
    .ToContainer("Gateways")
    .HasPartitionKey(f => f.Id)
    .HasDefaultId();

2. 修改容器分区键路径： 如果可能，将现有容器的分区键路径从/Id改为/id，这样可以直接使用9.0的默认行为。

相关注意事项

1. 鉴别器变更： EF Core 9.0同时将默认的鉴别器名称从Discriminator改为标准的$type。如果应用程序依赖旧的鉴别器名称，需要进行相应调整。

2. 性能影响： 新设计减少了存储空间占用和网络传输数据量，对性能有轻微正面影响。

3. 查询兼容性： 所有通过EF Core进行的查询不受影响，框架会正确处理属性映射。

最佳实践建议

1. 新项目应直接使用9.0的默认行为
2. 现有项目在升级时：
   • 评估是否可以直接修改分区键路径
   • 如不能修改，使用HasDefaultId()保持兼容
   • 考虑逐步迁移到新标准
3. 全面测试数据访问层，特别是涉及直接操作JSON文档的场景

这一变更是EF Core团队为更好地遵循Cosmos DB标准而做出的改进，虽然短期内可能带来一些升级工作，但从长期来看有助于建立更清晰、更标准的数据模型。