> This page location: /docs.md > /docs/drivers.md > /docs/languages/csharp.md > /docs/drivers/csharp/current.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Serialization

## 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](https://en.wikipedia.org/wiki/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.](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Serializers.html)

## ObjectSerializer

The `ObjectSerializer` class allows serialization and deserialization only of types that are considered safe. When you construct an `ObjectSerializer`, you can pass in a delegate of type `Func<Type, bool>`. This delegate accepts an object type and returns a boolean value indicating whether the type is safe for serialization.

In most cases, pass in the `ObjectSerializer.DefaultAllowedTypes()` delegate. This method returns true for several well-known framework types that we have deemed safe. To serialize custom types, create a boolean expression that evaluates to `true` for the types you want to include. Then, add this expression to the end of the delegate you pass to the `ObjectSerializer` constructor.

In the following example, the `ObjectSerializer` will serialize and deserialize any type that is allowed by `ObjectSerializer.DefaultAllowedTypes()` or whose full name begins with `"MyNamespace"`:

```csharp
var objectSerializer = new ObjectSerializer(type => ObjectSerializer.DefaultAllowedTypes(type)
    || type.FullName.StartsWith("MyNamespace"));
BsonSerializer.RegisterSerializer(objectSerializer);
```

To allow anonymous types to be serialized, add the boolean expression `type.FullName.StartsWith("<>f__AnonymousType"))` to your delegate, as shown in the following example:

```csharp
var objectSerializer = new ObjectSerializer(type => ObjectSerializer.DefaultAllowedTypes(type)
    || type.FullName.StartsWith("<>f__AnonymousType"));
BsonSerializer.RegisterSerializer(objectSerializer);
```

Create and register your `ObjectSerializer` at the start of your program, before doing anything else.

## 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:

```csharp
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:

```csharp
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:

```csharp
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](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.IBsonIdProvider.html) interface provides the `GetDocumentId()` and `SetDocumentId()` methods, and is useful if the object you are serializing uses an `_id` type other than `ObjectId`.

The following code example shows a custom serializer that implements the `IBsonIdProvider` interface:

```csharp
class CustomPersonSerializer : IBsonSerializer, IBsonIdProvider
{
   public Type ValueType => typeof(Person);
   
   public bool GetDocumentId(object document, out object id, out Type idNominalType, out IIdGenerator idGenerator)
   {
      var person = (Person)document;
      id = person.Id;
      idNominalType = typeof(string);
      idGenerator = new StringObjectIdGenerator();
      return true;
   }
   
   public void SetDocumentId(object document, object id)
   {
      var person = (Person)document;
      person.Id = (string)id;
   }
   
   public object Deserialize(BsonDeserializationContext context, BsonDeserializationArgs args)
   {
      // Deserialization logic
   }
   
   public void Serialize(BsonSerializationContext context, BsonSerializationArgs args, object value)
   {
      // Serialization logic
   }
}
```

### IBsonDocumentSerializer

Implementing the [IBsonDocumentSerializer](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.IBsonDocumentSerializer.html) 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.

The following code example shows a custom serializer that implements the `IBsonDocumentSerializer` interface:

```csharp
class CustomPersonSerializer : IBsonSerializer, IBsonDocumentSerializer
{
   public Type ValueType => typeof(Person);
   
   public bool GetMemberSerializationInfo(string memberName, out BsonSerializationInfo serializationInfo)
   {
      switch (memberName)
      {
         case "Name":
            serializationInfo = new BsonSerializationInfo("name", new StringSerializer(), typeof(string));
            return true;
         case "Age":
            serializationInfo = new BsonSerializationInfo("age", new Int32Serializer(), typeof(int));
            return true;
         default:
            serializationInfo = null;
            return false;
      }
   }
   
   public object Deserialize(BsonDeserializationContext context, BsonDeserializationArgs args)
   {
      // Deserialization logic
   }
   
   public void Serialize(BsonSerializationContext context, BsonSerializationArgs args, object value)
   {
      // Serialization logic
   }
}
```

### IBsonArraySerializer

Implementing the [IBsonArraySerializer](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.IBsonArraySerializer.html) interface enables the driver to access serialization information for individual items in an array.

The following code example shows a custom serializer that implements the `IBsonArraySerializer` interface:

```csharp
class CustomListSerializer : IBsonSerializer, IBsonArraySerializer
{
   public Type ValueType => typeof(List<string>);
   
   public bool TryGetItemSerializationInfo(out BsonSerializationInfo serializationInfo)
   {
      serializationInfo = new BsonSerializationInfo("item", new StringSerializer(), typeof(string));
      return true;
   }
   
   public object Deserialize(BsonDeserializationContext context, BsonDeserializationArgs args)
   {
      // Deserialization logic
   }
   
   public void Serialize(BsonSerializationContext context, BsonSerializationArgs args, object value)
   {
      // Serialization logic
   }
}
```

## 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](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.CamelCaseElementNameConvention.html) | Converts element names to camel case during serialization and deserialization. |
| [EnumRepresentationConvention](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.EnumRepresentationConvention.html) | Converts enum values to a specified representation during serialization and deserialization. |
| [IgnoreExtraElementsConvention](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.IgnoreExtraElementsConvention.html) | Specifies whether to ignore extra elements in a document during deserialization. |
| [ObjectSerializerAllowedTypesConvention](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.ObjectSerializerAllowedTypesConvention.html) | Specifies which types are allowed to be serialized using an object serializer. |

To view a full list of available conventions, see the [Conventions](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.html) 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:

```csharp
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>](https://learn.microsoft.com/en-us/dotnet/api/system.memory-1?view=net-8.0) and [ReadOnlyMemory\<T>](https://learn.microsoft.com/en-us/dotnet/api/system.readonlymemory-1?view=net-8.0) 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:

```csharp
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:

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

**Tip: Model Vectors**

[Run a MongoDB Vector Search Query](https://www.mongodb.com/docs/drivers/csharp/current/atlas-vector-search.md#std-label-csharp-atlas-vector-search) involves creating and querying large numerical arrays. If your application uses MongoDB 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](https://www.mongodb.com/docs/drivers/csharp/current/atlas-vector-search.md#std-label-csharp-supported-vector-types) in the MongoDB Vector Search guide.

## Additional Information

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

- [Customize Class Mapping](https://www.mongodb.com/docs/drivers/csharp/current/serialization/class-mapping.md#std-label-csharp-class-mapping)

- [POCOs](https://www.mongodb.com/docs/drivers/csharp/current/serialization/poco.md#std-label-csharp-poco)

- [Polymorphic Objects](https://www.mongodb.com/docs/drivers/csharp/current/serialization/polymorphic-objects.md#std-label-csharp-polymorphism)

- [GUIDs](https://www.mongodb.com/docs/drivers/csharp/current/serialization/guids.md#std-label-csharp-guids)

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

- [SerializerRegistry](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.BsonSerializer.SerializerRegistry.html)

- [BsonSerializer](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.BsonSerializer.html)

- [IBsonSerializer](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.IBsonSerializer.html)

- [ConventionPack](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.ConventionPack.html)

- [ConventionRegistry](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.ConventionRegistry.html)

- [Register()](https://mongodb.github.io/mongo-csharp-driver/3.13.0/api/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.ConventionRegistry.Register.html#MongoDB_Bson_Serialization_Conventions_ConventionRegistry_Register_System_String_MongoDB_Bson_Serialization_Conventions_IConventionPack_System_Func_System_Type_System_Boolean__)
