ASP.NET 使用 Cosmos DB 时如何实现忽略未知额外元素功能？

分两种常用开发场景配置即可实现自动忽略所有未知元素的需求，效果等价于MongoDB的[BsonIgnoreExtraElements]特性： #

场景1：使用原生Azure Cosmos DB .NET SDK（V3/V4） #

在初始化CosmosClient时配置序列化规则即可全局生效，无需为每个实体单独添加特性：

基于默认Newtonsoft.Json序列化器配置 #

using Newtonsoft.Json;
using Microsoft.Azure.Cosmos;

var cosmosClient = new CosmosClient("你的Cosmos DB连接串", new CosmosClientOptions
{
    Serializer = new CosmosJsonDotNetSerializer(new JsonSerializerSettings
    {
        // 核心配置：反序列化时自动跳过所有未在实体类中定义的属性
        MissingMemberHandling = MissingMemberHandling.Ignore
    })
});

基于System.Text.Json序列化器配置 #

using System.Text.Json;
using Microsoft.Azure.Cosmos;

var cosmosClient = new CosmosClient("你的Cosmos DB连接串", new CosmosClientOptions
{
    Serializer = new CosmosSystemTextJsonSerializer(new JsonSerializerOptions
    {
        // 核心配置：反序列化时自动跳过所有未匹配的属性
        UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip
    })
});

场景2：使用EF Core for Cosmos DB #

EF Core 7.0及以上版本 #

直接在DbContext的配置中开启全局规则即可：

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.UseCosmos(
        "你的Cosmos DB连接串",
        "你的数据库名称",
        cosmosOptions =>
        {
            // 开启全局忽略未映射的属性
            cosmosOptions.IgnoreUnmappedProperties();
        });
}

EF Core 6及更低版本 #

自定义序列化器，将上述Newtonsoft.Json/System.Text.Json的忽略未知属性配置注入到EF Core的Cosmos序列化规则中即可。 #

可选：单个实体独立配置 #

如果不需要全局生效，仅需要给指定实体开启忽略未知属性的能力，直接在实体类上添加对应序列化特性即可：

• 适配Newtonsoft.Json：[JsonObject(MissingMemberHandling = MissingMemberHandling.Ignore)]
• 适配System.Text.Json：[JsonUnmappedMemberHandling(JsonUnmappedMemberHandling.Skip)]

效果说明 #

所有配置均不需要提前预知新增字段的名称，所有未在当前版本实体类中定义的属性都会在反序列化阶段自动跳过，后续对接同一数据库的服务新增字段时，完全不会影响旧版本服务的运行，也不需要回溯旧代码补充[JsonIgnore]配置，大幅降低维护成本。

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