EF Core 9中Cosmos提供程序主键映射问题的分析与解决

问题背景

在EF Core 9版本中，使用Cosmos DB提供程序时出现了一个关于主键映射的行为变更。当实体类没有显式定义Id或<实体名>Id属性时，即使通过.HasKey()方法指定了主键属性，该属性也不会自动映射到Cosmos文档的id字段。

问题表现

在EF Core 8及之前版本中，以下配置可以正常工作：

modelBuilder.Entity<PlanningMovement>(builder =>
{
    builder.ToContainer(PlanningMovementContainerName)
        .HasNoDiscriminator()
        .HasPartitionKey(m => m.MovementId)
        .HasKey(m => m.MovementId);

    builder.UseETagConcurrency();

    builder.Property(m => m.MovementId)
        .ToJsonProperty("movementId");
});

但在EF Core 9中，同样的配置会抛出异常：

System.InvalidOperationException: The entity type 'PlanningMovement' does not have a property mapped to the 'id' property in the database. Add a property mapped to 'id'.

技术分析

这个问题源于EF Core 9对Cosmos DB提供程序的模型验证逻辑进行了调整。在之前版本中，当实体没有显式的Id属性时，EF Core会自动将使用.HasKey()指定的主键属性映射到Cosmos文档的id字段。但在EF Core 9中，这种行为发生了变化，需要更明确的配置。

解决方案

有两种方法可以解决这个问题：

方法一：使用HasGeneratedId方法

这是官方推荐的解决方案，明确告诉EF Core需要为实体创建一个生成属性来映射到Cosmos的id字段：

modelBuilder.Entity<PlanningMovement>(builder =>
{
    builder.ToContainer(PlanningMovementContainerName)
        .HasNoDiscriminator()
        .HasPartitionKey(m => m.MovementId)
        .HasKey(m => m.MovementId);

    builder.UseETagConcurrency();
    builder.HasGeneratedId();  // 添加这一行

    builder.Property(m => m.MovementId)
        .ToJsonProperty("movementId");
});

方法二：显式映射Id属性

另一种方法是直接在实体类中添加一个Id属性，并将其映射到Cosmos的id字段：

public class PlanningMovement
{
    public string Id { get; set; }  // 映射到Cosmos的id字段
    public string MovementId { get; set; }  // 分区键
    public string Name { get; set; }
}

// 配置
modelBuilder.Entity<PlanningMovement>(builder =>
{
    builder.ToContainer(PlanningMovementContainerName)
        .HasNoDiscriminator()
        .HasPartitionKey(m => m.MovementId)
        .HasKey(m => m.Id);  // 使用Id作为主键

    builder.UseETagConcurrency();

    builder.Property(m => m.MovementId)
        .ToJsonProperty("movementId");
});

最佳实践建议

1. 明确性优于隐式行为：虽然EF Core 9的改变可能带来一些迁移成本，但显式配置通常比隐式行为更可靠，也更容易理解和维护。

2. 文档一致性：确保Cosmos文档中的id字段与EF Core中的映射一致，这对于数据迁移和查询性能都很重要。

3. 分区键设计：在Cosmos DB中，分区键的选择对性能有重大影响。确保分区键(movementId在本例中)与业务查询模式匹配。

4. 版本升级测试：从EF Core 8升级到9时，建议全面测试Cosmos DB相关的功能，特别是主键和分区键的配置。

总结

EF Core 9对Cosmos DB提供程序的这一变更强调了配置的明确性。虽然需要一些调整，但这种改变有助于避免潜在的混淆和错误。开发人员应该评估自己的实体模型，选择最适合的解决方案来确保平滑升级。