POCOs

序列化只读属性

如果属性是只读的，自动映射器不会将其包含在类映射中用于序列化。要强制自动映射器将属性包含在类映射中，将[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命名约定很常见，但使用[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#转换规范。

设置字段顺序

驱动程序将属性序列化为BSON字段，其顺序与POCO中指定的顺序一致。为了将属性按自定义顺序存储以匹配现有模式，您可以在[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，则驱动程序将它们按默认顺序序列化，在这些有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#驱动程序还包括验证Id属性并在ID无效时抛出异常的IIdGenerator类型。以下表格列出了这些类型。

在以下代码示例中，如果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类使用DateTime作为DateOfBirth属性。[BsonDateTimeOptions(DateOnly = true)]属性表示该属性仅包含日期。

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

您还可以使用[BsonDateTimeOptions()]属性来指定DateTime属性的DateTimeKind。在以下代码示例中，PatientRecord类具有一个类型为DateTime的AppointmentTime属性。[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 实例序列化为的格式。此枚举包括以下成员

• Document：（默认）驱动程序将 Dictionary 序列化为一个 BsonDocument。字典中的每个条目都是一个具有与条目键相同的名称和与条目值相等的值的 BsonElement。您只能使用此表示法，当字典中的所有键都是也是有效的 BsonElement 名称的字符串时。

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

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

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

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()]

• 约定包

• InsertOne()