使用Entity Framework与Cosmos DB更新实体时遇异常的解决咨询

这个问题的核心是EF Core Cosmos提供程序的键映射规则，以及Cosmos DB本身的文档要求导致的追踪错误。我们一步步拆解原因和解决方案：

可能的原因 #

1. Cosmos文档的系统id字段缺失或为空：Cosmos DB要求每个文档必须有一个小写的id系统字段，这是Cosmos的强制要求。如果你的文档里id字段为null，或者没有这个字段，EF Core会把它识别为一个alternate key，进而抛出这个异常。
2. 实体属性与Cosmos字段映射不匹配：EF Core Cosmos默认会将实体的Id（或<EntityName>Id）属性映射到Cosmos的id字段。如果你的实体Id映射到了Cosmos的大写Id字段（而非系统id），EF Core可能会把未映射的系统id当成alternate key，而它的值为空就会触发错误。
3. 实体类存在多余的id属性：如果你的User类里同时定义了大写Id和小写id两个属性，EF Core可能会自动将小写id标记为alternate key，一旦它为空就会报错。

解决方案 #

方案1：修正实体与Cosmos的键映射（推荐） #

确保实体的主键正确映射到Cosmos的系统id字段，同时保证Cosmos文档的id字段有有效值（可以和你的业务Id值一致）：

// 在DbContext的OnModelCreating方法中配置
modelBuilder.Entity<User>()
    .HasKey(p => p.Id)
    .ToJsonProperty("id"); // 显式指定将实体Id映射到Cosmos的系统id字段

之后，确保你的Cosmos文档中id字段不为空（可以设置为和Id相同的Guid值），这样EF Core就能正确追踪实体的主键，不会再把id当成alternate key。

方案2：如果需要保留Cosmos的大写Id字段 #

如果你因为业务原因必须保留Cosmos文档中的大写Id字段，那么需要：

1. 确保Cosmos文档的系统id字段有有效值（比如和Id相同）
2. 配置EF Core忽略多余的键映射，或者显式定义主键和系统id的关系：

modelBuilder.Entity<User>()
    .HasKey(p => p.Id)
    .ToJsonProperty("Id"); // 映射到大写Id字段
    // 同时配置系统id字段的映射，确保它有值
    .Property(p => p.Id)
    .HasColumnName("id"); // 额外将Id映射到系统id字段（这样Cosmos里同时有id和Id，值相同）

或者，如果你不需要系统id字段参与业务，也可以在实体中添加对应属性并确保它不为空：

public class User
{
    public Guid Id { get; set; }
    public string id { get; set; } // 对应Cosmos的系统id字段
}

然后在保存前设置user.id = user.Id.ToString();，确保它不为空。

方案3：正确的更新实体流程 #

无论哪种映射方式，更新实体时要确保EF Core能正确识别实体的状态：

• 如果是从数据库查询出的实体：直接修改属性后调用SaveChanges即可，不需要调用Update：

  var userToUpdate = await _dbContext.Users.FindAsync("My-Guid-Id");
  if (userToUpdate != null)
  {
      userToUpdate.Email = "new.email@example.com";
      await _dbContext.SaveChangesAsync();
  }
  

• 如果是断开连接的实体（比如前端传入）：先附加实体，再标记为修改状态：

  _dbContext.Users.Attach(user);
  _dbContext.Entry(user).State = EntityState.Modified;
  await _dbContext.SaveChangesAsync();
  

避免直接调用_dbContext.Update(entity)，除非你能确保实体的所有键属性（包括EF Core识别的alternate key）都有有效值。

内容的提问来源于stack exchange，提问作者Tobias Moe Thorstensen