Class Mapping

Overview

In this guide, you can learn how to customize the way the MongoDB .NET/C# Driver maps BSON documents to and from C# classes. You can read this page to learn more about the default class mapping behavior, or if you need to customize the way the driver serializes or deserializes your data.

You can also use POCO attributes to set serialization behavior. To learn more, see the POCOs guide.

Automatic Class Mapping

When you use a class, rather than a BsonDocument, to represent data in a MongoDB collection, the .NET/C# Driver automatically creates a class map that it uses to serialize or deserialize your data. It does this mapping by matching the name of the field in the document to the name of the property in the class.

Manually Creating A Class Map

You can bypass the driver's automatic class mapping functionality, and manually define the class map by using the RegisterClassMap() method.

The following example defines a Person class:

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
}

The following code demonstrates how to register the class map for the Person class:

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
    classMap.MapMember(p => p.Name);
    classMap.MapMember(p => p.Age);
    classMap.MapMember(p => p.Hobbies);
});

You can also manually map a subset of class properties, while still allowing the driver to automatically map the remaining properties. To do this, register a class map and call the AutoMap() method before manually specifying your properties.

In the following code example, the AutoMap() method maps all properties of the Person class, then manually adjusts the mapping for the Hobbies field:

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
    classMap.AutoMap();
    classMap.MapMember(p => p.Hobbies).SetElementName("favorite_hobbies");
});

Customize Class Serialization

You can customize how the driver serializes and deserializes documents at the class level by applying attributes to the class or by calling methods while registering a class map.

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
     classMap.AutoMap();
     classMap.UnmapMember(p => p.Age);
});

[BsonIgnoreExtraElements]
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
}

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
     classMap.AutoMap();
     classMap.SetIgnoreExtraElements(true);
});

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
     classMap.AutoMap();
     classMap.MapIdMember(p => p.Identifier);
});

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
     classMap.AutoMap();
     classMap.IdMemberMap.SetSerializer(new StringSerializer(BsonType.ObjectId));
});

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
     classMap.AutoMap();
     classMap.MapIdMember(p => p.Identifier).SetIdGenerator(StringObjectIdGenerator.Instance);
});

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
     classMap.AutoMap();
     classMap.IdMemberMap.SetSerializer(new GuidSerializer(GuidRepresentation.Standard));
});

Mapping with Constructors

By default, the .NET/C# Driver can automatically map a class only if the class has a constructor with no arguments. If you want the driver to use a constructor that accepts one or more arguments, you can add the BsonConstructor attribute to the constructor. In this case, the driver examines the types to determine how to map the constructor arguments to class properties or fields.

When the driver creates a class map for the following Person class, it will use the constructor marked with the BsonConstructor attribute. The name argument will map to the Name property and the age argument will map to the Age property.

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
    [BsonConstructor]
    public Person(string name, string age)
    {
        Name = name;
        Age = age;
    }
}

You can also specify the constructor to use when registering your class map:

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
    public Person(string name, string age)
    {
        Name = name;
        Age = age;
    }
}
BsonClassMap.RegisterClassMap<Person>(classMap =>
{
    classMap.AutoMap();
    classMap.MapCreator(p => new Person(p.Name, p.Age));
});

Customize Property Serialization

You can customize how the driver serializes a class property by adding attributes to the property. For more information about custom property serialization, see Custom Serialization.

public class Person
{
    public string Name { get; set;
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
    [BsonExtraElements]
    public BsonDocument ExtraElements {get; set;}
}

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
    classMap.AutoMap();
    classMap.MapExtraElementsMember(p => p.ExtraElements);
});

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
    public bool ShouldSerializeAge()
    {
       return Age != 0;
    }
}

BsonClassMap.RegisterClassMap<Employee>(classMap =>
{
    classMap.AutoMap();
    classMap.MapMember(p => c.Age).SetShouldSerializeMethod(
        obj => ((Person) obj).Age != 0
    );
});

Additional Information

For more information on using C# classes, see POCOs.

API Documentation

• BsonClassMap

• RegisterClassMap

• AutoMap