Docs Menu

Docs HomeDevelop ApplicationsMongoDB DriversC#/.NET


On this page

  • Overview
  • Serializers
  • Serializer Registry
  • Custom Serializers
  • Opt-in Interfaces
  • IBsonIdProvider
  • IBsonDocumentSerializer
  • IBsonArraySerializer
  • Additional Information

In this guide, you can learn how to use the MongoDB .NET/C# Driver to perform serialization. Serialization is the process of mapping a C# object to a BSON document for storage in MongoDB.



To learn more about serialization, see the Serialization article on Wikipedia.

Serializers are classes that handle the translation of C# objects to and from BSON documents. Serializers implement the IBsonSerializer interface. The .NET/C# Driver has many built-in serializers made to handle primitive types, collection types, and custom classes.

For a full list of available serializers, see the Serializers namespace API documentation.

The serializer registry contains all registered serializers that are available to your application. Many of the built-in serializers are automatically registered to the serializer registry during startup of your application. However, before you can use a custom serializer, you must add it to the serializer registry, as shown in the following example:

BsonSerializer.RegisterSerializer(new CustomTypeSerializer());

To access the serializer registry, use the SerializerRegistry property of the BsonSerializer class as follows:

var intSerializer = BsonSerializer.SerializerRegistry.GetSerializer<int>();


The serializer registry is a global registry. This means that you cannot use multiple registries in a single application.

In some cases, you might need to create a custom serializer. When creating a custom serializer, implement the SerializerBase<T> abstract base class and override the Deserialize() and Serialize() methods.

The following code example shows a custom BsonRegularExpression serializer:

class CustomRegularExpressionSerializer : SerializerBase<RegularExpression>
public override RegularExpression Deserialize(BsonDeserializationContext context, BsonDeserializationArgs args)
var type = context.Reader.GetCurrentBsonType();
switch (type)
case BsonType.RegularExpression:
return context.Reader.ReadRegularExpression().AsRegex;
case BsonType.String:
var pattern = context.Reader.ReadString();
return new Regex(pattern);
throw new NotSupportedException($"Cannot convert a {type} to a RegularExpression.");
public override void Serialize(BsonSerializationContext context, BsonSerializationArgs args, RegularExpression value)

The .NET/C# Driver has several optional interfaces that your custom serializer class can implement, depending on the type of data the serializer handles.

The IBsonIdProvider interface provides the GetDocumentId() and SetDocumentId() methods, and is useful if the object you are serializing uses an _id type other than ObjectId.

Implementing the IBsonDocumentSerializer interface enables the driver to access the member information of the object you are serializing. This allows the driver to properly construct type-safe queries when using a custom serializer.

Implementing the IBsonArraySerializer interface enables the driver to access serialization information for individual items in an array.

To learn more about using the .NET/C# Driver to serialize C# objects, see the following pages:

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

← BSON Operations