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

Serialization

On this page

  • Overview
  • Serializers
  • Serializer Registry
  • Register a Serializer
  • Access a Serializer from the Registry
  • Custom Serializers
  • Opt-in Interfaces
  • IBsonIdProvider
  • IBsonDocumentSerializer
  • IBsonArraySerializer
  • Conventions
  • Improve Array Serialization Performance
  • 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.

Register a Serializer

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

After you register the serializer, the driver uses it to serialize any values that are mapped by the serializer.

Access a Serializer from the Registry

To access a specific serializer from the 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

To create your own custom serializer, implement the IBsonSerializer base class, set the ValueType member, and override the Deserialize() and Serialize() methods.

The following code example shows a custom BsonRegularExpression serializer:

class CustomRegularExpressionSerializer : IBsonSerializer
{
   public Type ValueType => typeof(Regex);
   public object Deserialize(BsonDeserializationContext context, BsonDeserializationArgs args)
   {
      var type = context.Reader.CurrentBsonType;
      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 void Serialize(BsonSerializationContext context, BsonSerializationArgs args, object value)
   {
      var regex = (Regex) value;
      context.Writer.WriteRegularExpression(regex);
   }
}

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.

Conventions

Convention packs allow you to define and apply conventions to your classes and their members that the driver uses during serialization. Conventions specify how data is mapped between your C# objects and MongoDB documents without requiring you to decorate each class with attributes.

The .NET/C# Driver provides built-in conventions that you can use to customize the serialization process. The following table describes some of the built-in conventions:

Convention
Description

CamelCaseElementNameConvention

Converts element names to camel case during serialization and deserialization.

EnumRepresentationConvention

Converts enum values to a specified representation during serialization and deserialization.

IgnoreExtraElementsConvention

Specifies whether to ignore extra elements in a document during deserialization.

ObjectSerializerAllowedTypesConvention

Specifies which types are allowed to be serialized using an object serializer.

To view a full list of available conventions, see the Conventions class reference in the API Documentation.

You can register a convention by instantiating a ConventionPack with the specified conventions, then passing it to the ConventionRegistry.Register() method, as shown in the following example:

var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
ConventionRegistry.Register("CamelCaseConvention", camelCaseConvention, t => true);

Improve Array Serialization Performance

You can improve your application's performance by representing arrays of primitives as Memory<T> and ReadOnlyMemory<T> structs instead of by using types such as standard C# arrays or BsonArray objects. The driver implements fast serialization and deserialization paths for Memory<T> and ReadOnlyMemory<T>, which enhances speed and reduces memory usage.

Note

Truncation and overflow checks are not supported for Memory<T> or ReadOnlyMemory<T>, but these checks are implemented for standard arrays.

You can effect these performance improvements by storing the following primitive types in Memory<T> or ReadOnlyMemory<T> structs:

  • bool

  • sbyte

  • byte

  • char

  • short

  • ushort

  • int

  • uint

  • long

  • ulong

  • float

  • double

  • decimal

The following example defines a Line POCO that contains array fields modeled by Memory and ReadOnlyMemory structs:

public class Line
{
  public ObjectId Id { get; set; }
  public Memory<int> X { get; set; }
  public ReadOnlyMemory<float> Y { get; set; }
}

The following document represents how a sample Line object is represented in MongoDB:

{
  "_id": ...,
  "X": [ 1, 2, 3, 4, 5 ],
  "Y": [ 1, 1.409999966621399, 1.7300000190734863, 2, 2.240000009536743 ]
}

Tip

Model Vectors

Atlas Vector Search involves creating and querying large numerical arrays. If your application uses Atlas Vector Search, you might benefit from the performance improvements from using Memory and ReadOnlyMemory to store array representations of embeddings and query vectors. To learn more, see Supported Vector Embedding Types in the Atlas Vector Search guide.

Additional Information

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:

Back

Query

Next

Class Mapping