Docs Menu
Docs Home
/
Languages
/
C#/.NET
/
C#/.NET
/
Fundamentals

Serialization

On this page

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

Overview

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.

Tip

Serialization

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

Serializers

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.

Serializer Registry

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

Important

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

Custom Serializers

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<Regex>
{
    public override Regex 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);
          default:
              throw new NotSupportedException($"Cannot convert a {type} to a RegularExpression.");
      }
  }
  public override void Serialize(BsonSerializationContext context, BsonSerializationArgs args, Regex value)
  {
      context.Writer.WriteRegularExpression(value);
  }
}

Opt-in Interfaces

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

IBsonIdProvider

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.

IBsonDocumentSerializer

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.

IBsonArraySerializer

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

Additional Information

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

  • Class Mapping

  • POCOs

  • Polymorphic Objects

  • GUIDs

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

Back

Specify a Query

Next

Class Mapping