IDocumentClient.UpsertDocumentAsync未更新却插入重复ID问题咨询

这确实挺让人困惑的——按道理Upsert的核心逻辑就是“存在则更新，不存在则插入”，出现重复ID的情况肯定是某个环节没匹配上。我来帮你梳理下最常见的原因和对应的解决办法：

1. 文档ID的大小写不匹配 #

CosmosDB的id字段是大小写敏感的！举个例子：如果集合里已有ID为"User_123"的文档，但你Upsert时传入的ID是"user_123"，这会被CosmosDB判定为两个完全不同的ID，从而创建新文档而非更新原有文档。

你可以先通过CosmosDB门户直接查看现有文档的id值，和你代码中要Upsert的文档ID做精确对比，确保大小写完全一致。

2. 分区键未正确匹配（针对分区集合） #

如果你的CosmosDB集合是分区集合，Upsert操作需要同时满足两个条件才会触发更新：

• 文档的id完全匹配
• 分区键值完全匹配

假设你的分区键是"/department"，现有文档的分区键值是"Engineering"，但你Upsert时传入的分区键值是"engineering"（大小写问题），或者干脆没指定分区键参数，导致客户端自动计算的分区键和原有文档不一致，这时候哪怕ID相同，CosmosDB也会认为是不同分区下的文档，进而新增一条。

正确的做法是在Upsert时显式指定分区键：

var requestOptions = new RequestOptions
{
    PartitionKey = new PartitionKey("匹配现有文档的分区键值")
};
await client.UpsertDocumentAsync(collectionUri, yourDocument, requestOptions);

3. 实体类ID字段的序列化问题 #

CosmosDB的系统文档ID字段是小写的"id"，如果你的C#实体类中ID属性没有正确映射到这个字段，会导致序列化后生成的文档自带一个系统自动生成的id，而你以为的ID其实是自定义字段。

比如错误的写法：

public class Employee
{
    // 没有指定JsonProperty，序列化后会变成"Id"而非"id"
    public string Id { get; set; }
}

正确的写法是用JsonProperty标记映射到小写的"id"：

using Newtonsoft.Json;

public class Employee
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }
    // 其他业务字段...
}

4. 旧版SDK的潜在bug #

你使用的是VS2017，对应的CosmosDB SDK可能是较旧的Microsoft.Azure.DocumentDB包（而非新版的Microsoft.Azure.Cosmos）。旧版本SDK在某些边缘场景下可能存在Upsert逻辑的bug，导致行为不符合预期。

建议你尝试升级到兼容的最新SDK版本，然后重新测试Upsert操作，看问题是否消失。

5. 索引策略异常（少见） #

虽然默认情况下CosmosDB集合会自动索引id字段，但如果你的集合自定义了索引策略，不小心排除了id字段，可能会导致查询时出现“重复ID”的视觉错觉（实际文档的系统id是不同的，只是你查询展示的自定义ID相同）。

你可以登录CosmosDB门户，查看目标集合的索引策略，确认"id"字段被包含在索引范围内。

内容的提问来源于stack exchange，提问作者DeveloperInToronto