POCO

序列化只读属性

如果属性为只读，则自动映射器不会将其包含在类映射中以进行序列化。要强制自动映射器将属性包含在类映射中，则将 [BsonElement] 属性应用于该属性。

以下代码示例将 [BsonElement] 属性应用于 Clothing 类的 Upc 属性。Upc 为只读属性，因为它拥有 get 方法，但没有 set 方法。

public class Clothing
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    public bool InStock { get; set; }
    public double Price { get; set; }
    public List<string> ColorSelection { get; set; }
    [BsonElement]
    public int Upc { get; }
}

您还可以在注册类映射时添加只读属性，如以下示例所示：

BsonClassMap.RegisterClassMap<Clothing>(classMap =>
{
    classMap.AutoMap();
    classMap.MapProperty(c => c.Upc);
});

设置字段名称

驱动程序将 POCO 属性序列化为具有相同字段名称和大小写的 BSON 字段。要以不同名称存储属性，则使用 [BsonElement()] 属性。以下代码将 House 类的 YearBuilt 属性映射到序列化 BSON 文档中的 year_built 字段：

public class House
{
    public Guid Id { get; set; }
    [BsonElement("year_built")]
    public int YearBuilt { get; set; }
}

尽管在定义 C# 类时通常使用 Pascal case 命名规范，但使用 [BsonElement()] 属性允许您在 MongoDB 集合中选择不同的或自定义命名规范。

var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true);

选择类型表示

要将 C# 属性序列化为特定 BSON 类型，则使用 [BsonRepresentation()] 属性。仅当 C# 基元类型可转换为您指定的 BSON 类型时，此方法才有效。在以下代码示例中，在 C# 中定义为 char 的 YearBuilt 属性被序列化为 BSON Int32 类型：

public class House
{
    public Guid Id { get; set; }
    [BsonRepresentation(BsonType.Int32)]
    public char YearBuilt { get; set; }
}

有关有效类型转换的更多信息，请参阅 C# 转换规范。

设置字段顺序

驱动程序按照 POCO 中指定的顺序将属性序列化为 BSON 字段。要按照自定义顺序存储属性以匹配现有模式，可以在 [BsonElement()] 属性中指定 Order 命名参数。在以下代码示例中，驱动程序将 YearBuilt 属性存储在 Style 属性之后：

public class House
{
    public Guid Id { get; set; }
    [BsonElement(Order = 2)]
    public int YearBuilt { get; set; }
    [BsonElement(Order = 1)]
    public string Style { get; set; }
}

如果任何属性没有显式 Order，则驱动程序将在具有显式顺序的属性之后按默认顺序对其进行序列化。

识别 Id 属性

默认情况下，驱动程序会将名为 Id、id 或 _id 的任何公共属性映射到 BSON _id 字段。要明确选择映射到 _id 字段的属性，则使用 [BsonId()] 属性。以下代码示例将 Identifier 属性映射到 _id 字段：

public class House
{
    [BsonId]
    public string Identifier { get; set; }
}

省略空字段

默认情况下，驱动程序将未定义的属性序列化为具有 null 值的字段。要在序列化过程中忽略未定义属性，则使用 [BsonIgnore] 属性。以下代码展示了如何在 YearBuilt 属性未定义时阻止驱动程序序列化该属性：

public class House
{
    public Guid Id { get; set; }
    [BsonIgnore]
    public int YearBuilt { get; set; }
    public string Style { get; set; }
}

自定义默认值

在 C# 中，属性在赋值之前均为默认值。默认值取决于属性的数据类型。例如，引用类型属性的默认值为 null。

要为属性指定不同的默认值，则将 [BsonDefaultValue()] 属性应用于该属性并将所需默认值作为参数传递。

以下代码示例将 [BsonDefaultValue()] 属性应用于 YearBuilt 属性。在为该属性分配值之前，其值为 1900。

public class House
{
    public Guid Id { get; set; }
    [BsonDefaultValue(1900)]
    public int YearBuilt { get; set; }
}

还可以在注册类映射时为属性指定不同的默认值，如以下示例所示：

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(h => h.YearBuilt).SetDefaultValue(1900);
});

默认情况下，.NET/C# 驱动程序会序列化所有属性，包括那些包含默认值的属性。若要指示驱动程序忽略具有默认值的属性，则使用 [BsonIgnoreIfDefault] 属性。

以下代码示例将 [BsonIgnoreIfDefault] 属性应用于 YearBuilt 属性。如果此属性的值是其数据类型的默认值（int 属性为 0），则驱动程序将不会对其序列化。

public class House
{
    public Guid Id { get; set; }
    [BsonIgnoreIfDefault]
    public int YearBuilt { get; set; }
}

您还可以指示驱动程序在注册类映射时忽略包含默认值的属性，如以下示例所示：

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(h => h.YearBuilt).SetIgnoreIfDefault(true);
});

您可以为属性指定不同的默认值，并指示驱动程序忽略该属性（如果该属性包含此默认值）。为此，将 [BsonDefaultValue()] 和 [BsonIgnoreIfDefault] 属性应用于该属性，如以下代码示例所示：

public class House
{
    public Guid Id { get; set; }
    [BsonDefaultValue(1900)]
    [BsonIgnoreIfDefault]
    public int YearBuilt { get; set; }
}

前面的代码示例设置了以下序列化行为：

• 如果没有为 YearBuilt 属性赋值，则其指定默认值为 1900。

• 由于 1900 是此属性的默认值，因此如果该属性具有此值，则驱动程序将忽略该属性。

指定 ID 生成器

MongoDB 数据集中的每个文档都必须有一个唯一的 ID。将对象序列化为集合时，如果 Id 属性包含其数据类型的默认值，则 .NET/C# 驱动程序不会对其进行序列化。相反，驱动程序会为该属性生成唯一的 ID 值。

如果 Id 属性的类型为 Guid、ObjectId 或 string，则驱动程序可以自行生成 ID 值。如果 Id 属性是任何其他数据类型，则必须指定驱动程序用于生成值的 IIdGenerator 类型。要指定 IIdGenerator 类型，将 [BsonId(IdGenerator)] 属性应用于属性并将 IIdGenerator 类型作为参数传递。

.NET/C# 驱动程序包括以下 IIdGenerator 类型：

在以下代码示例中，如果 House 类的 Id 属性包含默认值 (null)，则驱动程序在序列化期间使用 COMB 算法生成唯一值：

public class House
{
    [BsonId(IdGenerator = typeof(CombGuidGenerator))]
    public Guid Id { get; set; }
}

您还可以在注册类映射时指定 IIdGenerator 类型，如以下示例所示：

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapIdMember(h => h.Id).SetIdGenerator(CombGuidGenerator.Instance);
});

BsonSerializer.RegisterIdGenerator(
  typeof(Guid),
  CombGuidGenerator.Instance
);

.NET/C# 驱动程序还包括 IIdGenerator 类型，用于验证 Id 属性并在 ID 无效时抛出异常。下表列出这些类型：

在以下代码示例中，如果 House 类的 Id 属性包含默认值 (null)，则驱动程序会抛出异常：

public class House
{
    [BsonId(IdGenerator = typeof(NullIdChecker))]
    public Guid Id { get; set; }
}

自定义 DateTime 序列化

要自定义 .NET/C# 驱动程序序列化 DateTime 属性的方式，则使用 [BsonDateTimeOptions()] 属性并将所需设置指定为参数。

如果 DateTime 属性仅表示日期，您可以对其应用 [BsonDateTimeOptions(DateOnly = true)] 属性。如果这样做，驱动程序将不会对该值执行任何时区转换。

在以下代码示例中，PatientRecord 类为 DateOfBirth 属性使用 DateTime。[BsonDateTimeOptions(DateOnly = true)] 属性指示该属性仅包含日期。

public class PatientRecord
{
    public Guid Id { get; set; }
    [BsonDateTimeOptions(DateOnly = true)]
    public DateTime DateOfBirth { get; set; }
}

您也可以使用 [BsonDateTimeOptions()] 属性指定 DateTime 属性的 DateTimeKind。在以下代码示例中，PatientRecord 类有一个 AppointmentTime 属性，其类型为 DateTime。[BsonDateTimeOptions(Kind = DateTimeKind.Local)] 属性指示属性值的时间部分为当地时间。当驱动程序序列化此属性时，它会将时间转换为 UTC，这是 MongoDB 中存储的时间的标准格式。

public class PatientRecord
{
    public Guid Id { get; set; }
    [BsonDateTimeOptions(Kind = DateTimeKind.Local)]
    public DateTime AppointmentTime { get; set; }
}

您还可以在注册类映射时指定前面的一个或两个 DateTime 选项：

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(p => p.DateOfBirth)
      .SetSerializer(new DateTimeSerializer(dateOnly: true));
   classMap.MapMember(p => p.AppointmentTime)
      .SetSerializer(new DateTimeSerializer(DateTimeKind.Local));
});

自定义字典序列化

DictionaryRepresentation 枚举定义 .NET/C# 驱动程序可用于将 Dictionary 实例进行序列化的格式。该枚举包括以下节点：

• 文档：（默认）驱动程序将 Dictionary 序列化为 BsonDocument。字典中的每个条目都是一个 BsonElement，其名称等于条目的键，值等于条目的值。仅当字典中的所有键也是有效 BsonElement 名称的字符串时，您才能使用此表示。

• ArrayOfArrays：驱动程序将字典序列化为 BsonArray。字典中的每个条目都是一个嵌套的二元素 BsonArray，其中包含条目的键和条目的值。

• ArrayOfDocuments：驱动程序将字典序列化为 BsonArray。字典中的每个条目都是 { k : key, v : value } 形式的嵌套 BsonDocument。由于键和值都用元素名称标记，因此您能够比 ArrayOfArrays 更直观地查询此格式。

在以下代码示例中，RoomSizes 属性是字典，其中包含房屋中的每个房间及其相应的大小。[BsonDictionaryOptions()] 属性指示 .NET/C# 驱动程序将此属性序列化为 BsonArray 对象，并将字典中的每个条目序列化为 { k : "<room>", v : <size> } 形式的 BsonDocument。

public class House
{
    public Guid Id { get; set; }
    [BsonDictionaryOptions(DictionaryRepresentation.ArrayOfDocuments)]
    public Dictionary<string, float> RoomSizes { get; set; }
}

您还可以在注册类映射时指定字典的序列化格式，如以下示例所示：

BsonClassMap.RegisterClassMap<House>(classMap =>
{
    classMap.AutoMap();
    classMAp.MapMember(h => h.RoomSizes)
      .SetSerializer(new DictionaryInterfaceImplementerSerializer<Dictionary<string, float>>
      (DictionaryRepresentation.ArrayOfDocuments));
});

API 文档

要进一步了解本指南所讨论的任何方法或类型，请参阅以下 API 文档：

• [BsonElement()]

• [BsonRepresentation()]

• [BsonId()]

• [BsonIgnore()]

• [BsonDefaultValue()]

• [BsonIgnoreIfDefault]

• [BsonDateTimeOptions()]

• [BsonDictionaryOptions()]

• ConventionPack

• InsertOne()