BsonSerializer序列化需确保对象非null、类可序列化且有无参构造函数；BsonDocument适合动态结构，注意时间字段传DateTime实例；反序列化默认区分大小写且要求字段存在，可用[BsonElement]绑定；多文档需手动添加4字节长度前缀。
用 BsonSerializer 序列化对象到 BSON 文件
直接调用 BsonSerializer 是最可控的方式，尤其当你需要精确控制字段序列化行为（比如忽略 null、自定义日期格式）时。它不依赖 MongoDB 服务，纯内存操作，适合离线生成 BSON 文件。
常见错误是传入 null 对象或未标记可序列化的类——BsonSerializer 会直接抛 ArgumentException 或 InvalidOperationException。
- 确保目标类有无参构造函数，或显式注册自定义序列化器
- 用
BsonSerializer.Serialize<t>(stream, obj)</t>，别漏掉stream.Position = 0（如果复用流） - 写入前建议用
using var fs = new FileStream(path, FileMode.Create)，避免文件句柄残留 - 注意：
BsonSerializer默认不处理Dictionary<string object></string>的深层嵌套类型，遇到object值可能报NotSupportedException
var person = new { Name = "Alice", Age = 30 };
using var fs = new FileStream("data.bson", FileMode.Create);
BsonSerializer.Serialize(fs, person);用 MongoDB.Bson 的 BsonDocument 构建再写入
如果你的数据结构动态性强（比如来自 JSON 配置、API 响应），用 BsonDocument 手动组装比反射序列化更稳妥，也更容易调试字段名和类型是否符合预期。
容易踩的坑是误用 BsonValue.Create() 处理 DateTime 或 ObjectId：它不会自动转成 BSON 原生类型，而是包成 BsonString，导致后续读取时类型丢失。
- 优先用
new BsonDocument { { "name", "Alice" }, { "ts", DateTime.UtcNow } }这种字面量方式 - 时间字段务必传
DateTime实例，不要先 ToString() - 写入文件前，用
doc.ToBson()得到byte[]，再写入文件，比直接序列化BsonDocument更少歧义 - 注意：
BsonDocument不支持循环引用，尝试添加自身会触发StackOverflowException
var doc = new BsonDocument { { "name", "Bob" }, { "score", 95.5 } };
File.WriteAllBytes("doc.bson", doc.ToBson());反序列化时字段名大小写/缺失字段怎么处理
从 BSON 文件读回来时，BsonSerializer.Deserialize<t></t> 默认严格匹配字段名（区分大小写），且要求所有非 nullable 字段在 BSON 中存在。一旦不匹配，就抛 FormatException 或静默跳过字段（取决于配置）。
这不是 bug，是 BSON 规范的严谨性体现。但实际中常因导出工具、跨语言协作导致字段名小写、下划线分隔或字段缺失。
- 加
[BsonElement("user_name")]显式绑定字段，比依赖命名约定更可靠 - 对可选字段，用
int?、string（而非string!）并配合[BsonDefaultValue(null)] - 全局关闭大小写敏感：注册时传
new JsonSerializerOptions { PropertyNamingPolicy = null }（仅限 .NET 6+ +System.Text.Json互操作场景） - 读取未知结构用
BsonDocument.Parse(File.ReadAllText("x.bson"))（⚠️仅限 UTF-8 编码的 BSON 文本，不是二进制 BSON 文件）
文件头、多文档、流式写入要注意什么
BSON 文件本身没有标准“文件头”。单个 BSON 文档就是一串连续字节；多个文档拼接时，必须手动处理长度前缀或分隔符，否则读取端无法知道哪里是一条记录的结束。
很多人以为直接把几个 BsonDocument.ToBson() 结果 Concat 起来就能当“BSON 文件”用，结果用 mongodump 或其他工具打不开——因为那只是字节拼接，不是合法的 BSON stream 格式。
- 若需存多文档，推荐每条前面写 4 字节长度（小端序），即 BSON spec 定义的
document length，这是最通用的兼容做法 - 不要用
StreamWriter写 BSON 二进制内容，会导致编码污染（如 UTF-8 BOM） - 大文件写入时，避免一次性
ToBson()全部加载内存，改用BsonBinaryWriter流式写入 - 确认文件是否真为 BSON：用十六进制编辑器看开头是否为
13 00 00 00（一个长度为 19 的最小文档）
C# 操作 BSON 文件的关键不在“能不能写”，而在于你是否清楚自己写的是「单文档二进制块」还是「多文档流协议」——后者没有现成封装，得自己按 spec 补长度头。很多问题其实卡在这一步。
