MongoDB文档映射C#对象异常：Header.id反序列化失败及值为null问题

问题场景 #

使用MongoDB.Driver与MongoDB.Bson开发时，执行查询代码var customer = collection.Find(filter).FirstOrDefault();时抛出System.FormatException，提示Element 'id'无法匹配Header类的字段或属性。为Customer和Header类添加[BsonIgnoreExtraElements]特性后，查询不再报错，但customer.Header.Id始终为null。

相关资源 #

MongoDB文档

{
  "_id": {
    "$oid": "65d5fa85e4eb515ee6f6301a"
  },
  "given_name": "Renata",
  "address_filled": false,
  "header": {
    "id": "0945f7cd-16a8-4ea6-b87f-c24e90dcfbc6"
  }
}

C#实体类

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;

public class Header
{
    [BsonElement("id")]
    public string Id { get; set; }
}

public class Customer
{
    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public ObjectId Id { get; set; }

    [BsonElement("given_name")]
    public string GivenName { get; set; }

    [BsonElement("address_filled")]
    public bool AddressFilled { get; set; }

    [BsonElement("header")]
    public Header Header { get; set; }
}

查询代码

using MongoDB.Driver;
using System;

class Program
{
    static void Main(string[] args)
    {
        var connectionString = "your_connection_string";
        var client = new MongoClient(connectionString);
        var database = client.GetDatabase("customers");
        var collection = database.GetCollection<Customer>("customers");

        var filter = Builders<Customer>.Filter.Eq("header.id", "0945f7cd-16a8-4ea6-b87f-c24e90dcfbc6");

        var customer = collection.Find(filter).FirstOrDefault();

        if (customer != null)
        {
            Console.WriteLine($"Customer Name: {customer.GivenName}");
            Console.WriteLine($"Header ID: {customer.Header.Id}");
        }
        else
        {
            Console.WriteLine("Customer not found.");
        }
    }
}

原因分析 #

1. 初始FormatException原因：MongoDB驱动默认将名为id的字段视为ObjectId类型，即使实体类中定义为string并添加[BsonElement("id")]，驱动仍会尝试用ObjectId的序列化逻辑解析文档中的字符串id，导致类型转换失败抛出异常。
2. 添加BsonIgnoreExtraElements后Header.Id为null：该特性让驱动忽略文档与实体类不匹配的字段，但并未修正id字段的序列化规则，驱动仍无法将字符串id正确映射到string类型的Id属性，因此属性值为null。

解决方案 #

方案1：显式指定属性序列化类型 #

在Header类的Id属性上添加[BsonRepresentation(BsonType.String)]，明确告知驱动按字符串类型处理该字段：

public class Header
{
    [BsonElement("id")]
    [BsonRepresentation(BsonType.String)]
    public string Id { get; set; }
}

修改后可移除[BsonIgnoreExtraElements]（若无需忽略其他字段），重新执行查询即可正确获取Header.Id的值。

方案2：全局配置序列化规则 #

若存在大量类似场景，可在程序启动时全局配置驱动的序列化逻辑，将特定字段的序列化规则统一设置：

// 针对Header类的Id属性单独配置序列化规则
BsonClassMap.RegisterClassMap<Header>(cm =>
{
    cm.AutoMap();
    cm.GetMemberMap(h => h.Id)
        .SetElementName("id")
        .SetSerializer(new StringSerializer(BsonType.String));
});

方案3：验证查询过滤条件 #

当前查询过滤条件Builders<Customer>.Filter.Eq("header.id", "...")写法正确，无需修改，只需确保实体类映射规则正确即可。

内容的提问来源于stack exchange，提问作者Eduardo Lúcio