Serialize Documents with the CSharp Driver

Opt-In¶

A majority of classes will have their properties mapped automatically. There are some circumstances where this does not happen. For instance, if your property is read-only, it will not get included in the automapping of a class by default. In order to include the member, you can use the BsonElementAttribute.

public class MyClass {
    private readonly string _someProperty;

    [BsonElement]
    public string SomeProperty
    {
        get { return _someProperty; }
    }
}

The same result can be achieved without using attributes with the following initialization code:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.MapProperty(c => c.SomeProperty);
});

Element name¶

To specify an element name using attributes, write:

public class MyClass {
    [BsonElement("sp")]
    public string SomeProperty { get; set; }
}

The same result can be achieved without using attributes with the following initialization code:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.SomeProperty).SetElementName("sp");
});

Note that we are first automapping the class and then overriding one particular piece of the class map. If you didn’t call AutoMap first then GetMemberMap would throw an exception because there would be no member maps.

Element Order¶

If you want precise control over the order of the elements in the BSON document you can use the Order named parameter to the BsonElement attribute:

public class MyClass {
    [BsonElement("sp", Order = 1)]
    public string SomeProperty { get; set; }
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.SomeProperty).SetElementName("sp").SetOrder(1);
});

Any fields or properties that do not have an explicit Order will occur after those that do have an Order.

Identifying the Id Field or Property¶

To identify which field or property of a class is the Id you can write:

public class MyClass {
    [BsonId]
    public string SomeProperty { get; set; }
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.SetIdMember(cm.GetMemberMap(c => c.SomeProperty));
});

When not using AutoMap, you can also map a field or property and identify it as the Id in one step as follows:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.MapIdProperty(c => c.SomeProperty);
    // mappings for other fields and properties
});

Selecting an IdGenerator to Use for an Id Field or Property¶

When you Insert a document the C# driver checks to see if the Id member has been assigned a value, and if not, generates a new unique value for it. Since the Id member can be of any type, the driver requires the help of a matching IdGenerator to check whether the Id has a value assigned to it and to generate a new value if necessary. The driver has the following IdGenerators built-in:

• BsonObjectIdGenerator
• CombGuidGenerator
• GuidGenerator
• NullIdChecker
• ObjectIdGenerator
• StringObjectIdGenerator
• ZeroIdChecker<T>

Some of these IdGenerators are used automatically for commonly used Id types:

• BsonObjectIdGenerator is used for BsonObjectId
• GuidGenerator is used for Guid
• ObjectIdGenerator is used for ObjectId
• StringObjectIdGenerator is used for strings represented externally as ObjectId

To select an IdGenerator to use for your Id field or property write:

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

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.IdMemberMap.SetIdGenerator(CombGuidGenerator.Instance);
});

You could also say that you want to use the CombGuidGenerator for all Guids. In this case you would write:

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

The NullIdChecker and ZeroIdChecker<T> IdGenerators can be used when you don’t have an IdGenerator for an Id type but you want to enforce that the Id is not null or zero. These pseudo-IdGenerators throw an exception if their GenerateId method is called. You can select it for an individual member just like a CombGuidGenerator was selected in the previous example, or you can turn on one or both of these IdGenerators for all types as follows:

BsonSerializer.UseNullIdChecker = true; // used for reference types
BsonSerializer.UseZeroIdChecker = true; // used for value types

Ignoring a Field or Property¶

When constructing a class map manually you can ignore a field or property simply by not adding it to the class map. When using AutoMap you need a way to specify that a field or property should be ignored. To do so using attributes write:

public class MyClass {
    [BsonIgnore]
    public string SomeProperty { get; set; }
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.UnmapProperty(c => c.SomeProperty);
});

In this case AutoMap will have initially added the property to the class map automatically but then UnmapProperty will remove it.

Ignoring null Values¶

By default null values are serialized to the BSON document as a BSON Null. An alternative is to serialize nothing to the BSON document when the field or property has a null value. To specify this using attributes write:

public class MyClass {
    [BsonIgnoreIfNull]
    public string SomeProperty { get; set; }
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.SomeProperty).SetIgnoreIfNull(true);
});

Default Values¶

You can specify a default value for a field or property as follows:

public class MyClass {
    [BsonDefaultValue("abc")]
    public string SomeProperty { get; set; }
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.SomeProperty).SetDefaultValue("abc");
});

You can also control whether default values are serialized or not (the default is yes). To not serialize default values using attributes write:

public class MyClass {
    [BsonDefaultValue("abc")]
    [BsonIgnoreIfDefault]
    public string SomeProperty { get; set; }
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.SomeProperty)
        .SetDefaultValue("abc")
        .SetIgnoreIfDefault(true);
});

Ignoring a Member Based on a ShouldSerializeXyz Method¶

Sometimes the decision whether to serialize a member or not is more complicated than just whether the value is null or equal to the default value. You can write a method that determines whether a value should be serialized. Usually the method for member Xyz is named ShouldSerializeXyz. If you follow this naming convention then AutoMap will automatically detect the method and use it. For example:

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

    public bool ShouldSerializeDateOfBirth() {
        return DateOfBirth > new DateTime(1900, 1, 1);
    }
}

Or using initialization code instead of naming conventions:

BsonClassMap.RegisterClassMap<Employee>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.DateOfBirth).SetShouldSerializeMethod(
        obj => ((Employee) obj).DateOfBirth > new DateTime(1900, 1, 1)
    );
});

Identifying Required Fields¶

Normally, the deserializer doesn’t care if the document being deserialized doesn’t have a matching element for every field or property of the class. The members that don’t have a matching element simply get assigned their default value (or null if they don’t have a default value).

If you want to make an element in the document be required, you can mark an individual field or property like this:

public class MyClass {
    public ObjectId Id { get; set; }
    [BsonRequired]
    public string X { get; set; }
}

Or using initialization code instead attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.X).SetIsRequired(true);
});

Specifying the Serializer¶

There are times when a specific serializer needs to be used rather than letting the Bson library choose. This can be done in a couple of ways:

public class MyClass {
    public ObjectId Id { get; set; }
    [BsonSerializer(typeof(MyCustomStringSerializer))]
    public string X { get; set; }
}

Or using initialization code instead attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.X).SetSerializer(new MyCustomStringSerializer());
});

Serialization Options¶

Serialization of some classes can be more finely controlled using serialization options (which are represented using classes that implement the IBsonSerializationOptions interface). Whether a class uses serialization options or not, and which ones, depends on the particular class involved. The following sections describe the available serialization option classes and the classes that use them.

public class MyClass {
    [BsonDateTimeOptions(DateOnly = true)]
    public DateTime DateOfBirth { get; set; }
    [BsonDateTimeOptions(Kind = DateTimeKind.Local)]
    public DateTime AppointmentTime { get; set; }
}

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.DateOfBirth)
        .SetSerializationOptions(
            new DateTimeSerializationOptions { DateOnly = true });
    cm.GetMemberMap(c => c.AppointmentTime)
        .SetSerializationOptions(
            new DateTimeSerializationOptions { Kind = DateTimeKind.Local });
});

public enum DictionaryRepresentation {
    Dynamic,
    Document,
    ArrayOfArrays,
    ArrayOfDocuments
}

public class C {
    public ObjectId Id;
    [BsonDictionaryOptions(DictionaryRepresentation.ArrayOfDocuments)]
    public Dictionary<string, int> Values;
}

BsonClassMap.RegisterClassMap<C>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.Values)
        .SetSerializationOptions(DictionarySerializationOptions.ArrayOfDocuments);
});

public class MyClass {
    [BsonRepresentation(BsonType.Int32)]
    public char RepresentAsInt32 { get; set; }
    [BsonRepresentation(BsonType.String)]
    public char RepresentAsString { get; set; }
}

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.GetMemberMap(c => c.RepresentAsInt32)
        .SetRepresentation(BsonType.Int32);
    cm.GetMemberMap(c => c.RepresentAsString)
        .SetRepresentation(BsonType.String);
});

public class Employee {
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; }
    // other properties
}

BsonClassMap.RegisterClassMap<Employee>(cm => {
    cm.AutoMap();
    cm.IdMemberMap.SetRepresentation(BsonType.ObjectId);
});

Ignoring Extra Elements¶

When a BSON document is deserialized the name of each element is used to look up a matching field or property in the class map. Normally, if no matching field or property is found, an exception will be thrown. If you want to ignore extra elements during deserialization, use the following attribute:

[BsonIgnoreExtraElements]
public MyClass {
    // fields and properties
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.SetIgnoreExtraElements(true);
});

Supporting Extra Elements¶

You can design your class to be capable of handling any extra elements that might be found in a BSON document during deserialization. To do so, you must have a property of type BsonDocument and you must identify that property as the one that should hold any extra elements that are found (or you can name the property “ExtraElements” so that the default ExtraElementsMemberConvention will find it automatically). For example:

public MyClass {
    // fields and properties
    [BsonExtraElements]
    public BsonDocument CatchAll { get; set; }
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.SetExtraElementsMember(cm.GetMemberMap(c => c.CatchAll));
});

When a BSON document is deserialized any extra elements found will be stored in the extra elements BsonDocument property. When the class is serialized the extra elements will be serialized also. One thing to note though is that the serialized class will probably not have the elements in exactly the same order as the original document. All extra elements will be serialized together when the extra elements member is serialized.

Polymorphic Classes and Discriminators¶

When you have a class hierarchy and will be serializing instances of varying classes to the same collection you need a way to distinguish one from another. The normal way to do so is to write some kind of special value (called a “discriminator”) in the document along with the rest of the elements that you can later look at to tell them apart. Since there are potentially many ways you could discriminate between actual types, the default serializer uses conventions for discriminators. The default serializer provides two standard discriminators: ScalarDiscriminatorConvention and HierarchicalDiscriminatorConvention. The default is the HierarchicalDiscriminatorConvention, but it behaves just like the ScalarDiscriminatorConvention until certain options are set to trigger its hierarchical behavior (more on this later).

The default discriminator conventions both use an element named _t to store the discriminator value in the BSON document. This element will normally be the second element in the BSON document (right after the _id). In the case of the ScalarDiscriminatorConvention the value of _t will be a single string. In the case of the HierarchicalDiscriminatorConvention the value of _t will be an array of discriminator values, one for each level of the class inheritance tree (again, more on this later).

While you will normally be just fine with the default discriminator convention, you might have to write a custom discriminator convention if you must inter-operate with data written by another driver or object mapper that uses a different convention for its discriminators.

Setting the Discriminator Value¶

The default value for the discriminator is the name of the class (without the namespace part). You can specify a different value using attributes:

[BsonDiscriminator("myclass")]
public MyClass {
    // fields and properties
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<MyClass>(cm => {
    cm.AutoMap();
    cm.SetDiscriminator("myclass");
});

Specifying Known Types¶

When deserializing polymorphic classes it is important that the serializer know about all the classes in the hierarchy before deserialization begins. If you ever see an error message about an “Unknown discriminator” it is because the deserializer can’t figure out the class for that discriminator. If you are mapping your classes programmatically simply make sure that all classes in the hierarchy have been mapped before beginning deserialization. When using attributes and automapping you will need to inform the serializer about known types (i.e. subclasses) it should create class maps for. Here is an example of how to do this:

[BsonKnownTypes(typeof(Cat), typeof(Dog)]
public class Animal {
}

[BsonKnownTypes(typeof(Lion), typeof(Tiger)]
public class Cat : Animal {
}

public class Dog : Animal {
}

public class Lion : Cat {
}

public class Tiger : Cat {
}

The BsonKnownTypes attribute lets the serializer know what subclasses it might encounter during deserialization, so when Animal is automapped the serializer will also automap Cat and Dog (and recursively, Lion and Tiger as well).

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<Animal>();
BsonClassMap.RegisterClassMap<Cat>();
BsonClassMap.RegisterClassMap<Dog>();
BsonClassMap.RegisterClassMap<Lion>();
BsonClassMap.RegisterClassMap<Tiger>();

Scalar and Hierarchical Discriminators¶

Normally a discriminator is simply the name of the class (although it could be different if you are using a custom discriminator convention or have explicitly specified a discriminator for a class). So a collection containing a mix of different type of Animal documents might look like:

{ _t : "Animal", ... }
{ _t : "Cat", ... }
{ _t : "Dog", ... }
{ _t : "Lion", ... }
{ _t : "Tiger", ... }

Sometimes it can be helpful to record a hierarchy of discriminator values, one for each level of the hierarchy. To do this, you must first mark a base class as being the root of a hierarchy, and then the default HierarchicalDiscriminatorConvention will automatically record discriminators as array values instead.

To identify Animal as the root of a hierarchy use the BsonDiscriminator attribute with the RootClass named parameter:

[BsonDiscriminator(RootClass = true)]
[BsonKnownTypes(typeof(Cat), typeof(Dog)]
public class Animal {
}

// the rest of the hierarchy as before

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<Animal>(cm => {
    cm.AutoMap();
    cm.SetIsRootClass(true);
});
BsonClassMap.RegisterClassMap<Cat>();
BsonClassMap.RegisterClassMap<Dog>();
BsonClassMap.RegisterClassMap<Lion>();
BsonClassMap.RegisterClassMap<Tiger>();

Now that you have identified Animal as a root class, the discriminator values will look a little bit different:

{ _t : "Animal", ... }
{ _t : ["Animal", "Cat"], ... }
{ _t : ["Animal", "Dog"], ... }
{ _t : ["Animal", "Cat", "Lion"], ... }
{ _t : ["Animal", "Cat", "Tiger"], ... }

The main reason you might choose to use hierarchical discriminators is because it makes it possibly to query for all instances of any class in the hierarchy. For example, to read all the Cat documents we can write:

var query = Query.EQ("_t", "Cat");
var cursor = collection.FindAs<Animal>(query);
foreach (var cat in cursor) {
    // process cat
}

This works because of the way MongoDB handles queries against array values.

Implementing ISupportInitialize¶

The driver respects an entity implementing ISupportInitialize which contains 2 methods, BeginInit and EndInit. These method are called before deserialization begins and after it is complete. It is useful for running operations before or after deserialization such as handling schema changes are pre-calculating some expensive operations.

Make a Class Responsible for Its Own Serialization¶

One way you can customize how a class is serialized is to make it responsible for its own serialization. You do so by implementing the IBsonSerializable interface:

public class MyClass : IBsonSerializable {
    // implement Deserialize method
    // implement Serialize method
}

You also must implement the GetDocumentId and SetDocumentId methods. If your class is never used as a root document these methods can just be stubs that throw a NotSupportedException. Otherwise, return true from GetDocumentId if the value passed in has an Id, and set the Id value in SetDocumentId.

There is nothing else you have to do besides implementing this interface. The BSON Library automatically checks whether objects being serialized implement this interface and if so routes serialization calls directly to the classes.

This can be a very efficient way to customize serialization, but it does have the drawback that it pollutes your domain classes with serialization details, so there is also the option of writing a custom serializer as described next.

Supplementing the Default Serializer Provider¶

You can register your own serialization provider to supplement the default serializer. Register it like this:

IBsonSerializationProvider myProvider;
BsonSerializer.RegisterSerializationProvider(myProvider);

You should register your provider as early as possible. Your provider will be called first before the default serializer. You can delegate handling of any types your custom provider isn’t prepared to handle to the default serializer by returning null from GetSerializer.

Write a Custom Serializer¶

A custom serializer can handle serialization of your classes without requiring any changes to those classes. This is a big advantage when you either don’t want to modify those classes or can’t (perhaps because you don’t have control over them). You must register your custom serializer so that the BSON Library knows of its existence and can call it when appropriate.

If you write a custom serializer you will have to become familiar with the BsonReader and BsonWriter abstract classes, which are not documented here, but are relatively straightforward to use. Look at the existing serializers in the driver for examples of how BsonReader and BsonWriter are used.

To implement and register a custom serializer you would:

// MyClass is the class for which you are writing a custom serializer
public MyClass {
}

// MyClassSerializer is the custom serializer for MyClass
public MyClassSerializer : IBsonSerializer {
    // implement Deserialize
    // implement GetDefaultSerializationOptions
    // implement Serialize
}

// register your custom serializer
BsonSerializer.RegisterSerializer(
    typeof(MyClass),
    new MyClassSerializer()
);

You can also decorate the target class with a BsonSerializer attribute instead of using the BsonSerializer.RegisterSerializer method:

[BsonSerializer(typeof(MyClassSerializer))]
public MyClass {
}

The IBsonSerializer interface is all that is necessary for serialization. However, there are some extension interfaces that will enable further use in other parts of the api such as saving a class or LINQ.

If your class is used as a root document, you will need to implement the IBsonIdProvider interface in order for “Saving” the document to function. MongoCollection.Save requires a document identity in order to know if it should generate an insert or update statement. Below is the extension to the above MyClassSerializer.

public MyClassSerializer : IBsonSerializer, IBsonIdProvider {
    // ...

    // implement GetDocumentId
    // implement SetDocumentId
}

In order to enable LINQ to properly construct type-safe queries using a custom serializer, it needs access to member information or array information. If your custom serializer is for a class, as MyClassSerializer is above, then you should implement IBsonDocumentSerializer.

public MyClassSerializer : IBsonSerializer, IBsonDocumentSerializer {
    // ...

    // implement GetMemberSerializationInfo
}

If, however, your class is a collection that should be serialized as an array, it should implement IBsonArraySerializer.

public MyClassSerializer : IBsonSerializer, IBsonArraySerializer {
    // ...

    // implement GetItemSerializationInfo
}

To debug a custom serializer you can either Insert a document containing a value serialized by your custom serializer into some collection and then use the mongo shell to examine what the resulting document looks like. Alternatively you can use the ToJson method to see the result of the serializer without having to Insert anything into a collection as follows:

// assume a custom serializer has been registered for class C
var c = new C();
var json = c.ToJson();
// inspect the json string variable to see how c was serialized

Write a Custom Attribute¶

The auto mapping ability of BSON library utilizes attributes that implement IBsonClassMapModifier or IBsonMemberMapModifier for class level attributes or member level attributes respectively. Each of these interfaces have a single method called Apply that is passed a BsonClassMap or a BsonMemberMap with which it can use any of the public methods and properties to modify the map instance. One example of this would be to create an attribute called BsonEncryptionAttribute that is used to encrypt a string before sending it to the database and decrypt it when reading it back out.

View the existing attributes for examples of how these interfaces function.

Write a custom Id generator¶

You can write your own IdGenerator. For example, suppose you wanted to generate integer Employee Ids:

public class EmployeeIdGenerator : IIdGenerator {
    // implement GenerateId
    // implement IsEmpty
}

You can specify that this generator be used for Employee Ids using attributes:

public class Employee {
    [BsonId(IdGenerator = typeof(EmployeeIdGenerator)]
    public int Id { get; set; }
    // other fields or properties
}

Or using initialization code instead of attributes:

BsonClassMap.RegisterClassMap<Employee >(cm => {
    cm.AutoMap();
    cm.IdMember.SetIdGenerator(new EmployeeIdGenerator());
});

Alternatively, you can get by without an Id generator at all by just assigning a value to the Id property before calling Insert or Save.

Write a Custom Convention¶

Earlier in this tutorial we discussed replacing one or more of the default conventions. You can either replace them with one of the provided alternatives or you can write your own convention. Writing your own convention varies slightly from convention to convention.

As an example we will write a custom convention to find the Id member of a class (the default convention looks for a member named Id). Our custom convention will instead consider any public property whose name ends in Id to be the Id for the class. We can implement this convention as follows:

public class EndsWithIdConvention : IIdMemberConvention {
    public string FindIdMember(Type type) {
        foreach (var property in type.GetProperties()) {
            if (property.Name.EndsWith("Id")) {
                return property.Name;
            }
        }
        return null;
    }
}

And we can configure this convention to be used with all of our own classes by writing:

var myConventions = new ConventionProfile();
myConventions.SetIdMemberConvention(new EndsWithIdConvention());
BsonClassMap.RegisterConventions(
    myConventions,
    t => t.FullName.StartsWith("MyNamespace.")
);

A Member Has Been Added¶

When a new member is added to an entity, there is nothing that needs to be done other than restarting the application if you are using the auto mapping features. If not, then you will manually need to map the member in the same way all the other members are getting mapped.

Existing documents will not have this element and it will show up in your class with its default value. You can, of course, specify a default value.

A Member Has Been Removed¶

When a member has been removed from am entity, it will continue to exist in the documents. The serializer will throw an exception when this element is seen because it doesn’t know what to do with it. The 2 previously discussed items that can be used to combat this are the BsonIgnoreExtraElements class-level attribute and the ExtraElements members.

A Member Is Renamed¶

When a member has been renamed, it will exist in old documents with the old name and in new docuemnts with the new name. The way to handle incremental upgrades for this rename would be to implement an ExtraElements member in conjunction with ISupportInitialize. For example, let’s say that a class used to have a Name property which has now been split into a FirstName and a LastName property.

public class MyClass : ISupportInitialize {
    public string FirstName { get; set; }
    public string LastName { get; set; }

    [BsonExtraElements]
    public IDictionary<string, object> ExtraElements { get; set; }

    void ISupportInitialize.BeginInit() {
        // nothing to do at begin
    }

    void ISupportInitialize.EndInit() {
        object nameValue;
        if(!ExtraElements.TryGetValue("Name", out nameValue)) {
            return;
        }

        var name = (string)nameValue;

        // remove the Name element so that it doesn't get persisted back to the database
        ExtraElements.Remove("Name");

        // assuming all names are "First Last"
        var nameParts = name.Split(' ');

        FirstName = nameParts[0];
        LastName = nameParts[1];
    }
}

The Type of a Member Is Changed¶

If the .NET type is compatible with the old type (an integer is changed to a double), then everything will continue to work. Otherwise, a custom serializer or a migration script will be required.

The Representation of a Member Is Changed¶

If the representation of a member is changed and the representations are compatible, then everything will continue to work. Otherwise, a custom serializer or a migration script will be required.