在C#中处理Cosmos DB的JSON对象数组时Status字段为空的问题排查

开发API向Cosmos DB添加记录时，JSON请求体中的Status数组字段始终映射为null，怀疑是C#类定义问题，请求排查。

JSON请求体 #

{
    "name": "John", 
    "Status": [
        {
            "Status": "Closed",
            "StatusUpdatedDateTime": "2023-10-01T00:00:00Z",
            "StatusUpdatedBy": "XXX"
        }
    ]
}

当前C#类定义 #

public class TopObject
{
    public string name { get; set; }
    public List<Status> status { get; set; }
}

public class Status
{
    public string Status { get; set; }  
    public DateTimeOffset StatusUpdatedDateTime { get; set; }
    public string StatusUpdatedBy { get; set; }
}

核心问题：属性名称大小写不匹配 #

JSON请求体中的数组字段是大写开头的Status，但C#类TopObject中对应的属性是小写开头的status。默认JSON序列化器（如System.Text.Json或Newtonsoft.Json）会严格匹配名称大小写，导致字段无法映射，最终赋值为null。

修复方式（二选一即可） #

1. 统一属性名称大小写
   修改TopObject类的属性名称，与JSON字段名完全一致：

public class TopObject
{
    public string name { get; set; }
    // 改为大写开头的Status，匹配JSON字段名
    public List<Status> Status { get; set; }
}

public class Status
{
    public string Status { get; set; }  
    public DateTimeOffset StatusUpdatedDateTime { get; set; }
    public string StatusUpdatedBy { get; set; }
}

2. 使用序列化特性指定映射名称
   若不想修改C#属性名称，可通过特性明确指定对应的JSON字段名：

• 基于System.Text.Json：

using System.Text.Json.Serialization;

public class TopObject
{
    public string name { get; set; }
    [JsonPropertyName("Status")]
    public List<Status> status { get; set; }
}

• 基于Newtonsoft.Json：

using Newtonsoft.Json;

public class TopObject
{
    public string name { get; set; }
    [JsonProperty("Status")]
    public List<Status> status { get; set; }
}

额外可选配置 #

如果使用System.Text.Json，也可以全局配置序列化器忽略大小写，无需修改类或添加特性：

var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true
};
var topObject = JsonSerializer.Deserialize<TopObject>(jsonString, options);

不过更推荐前两种方式，明确的命名或特性映射可避免后续维护时出现歧义。

内容的提问来源于stack exchange，提问作者Himanshu Kumar Sinha