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

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

# Customize 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. Read this page to learn more about the default class mapping behavior, or if you must 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](https://www.mongodb.com/docs/drivers/csharp/current/serialization/poco.md#std-label-csharp-poco) 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.

**Important:**

Match the type of the property in your class to the type of the field in the document. The .NET/C# Driver instantiates a serializer based on the type of the property in your class. If the types don't match when the driver attempts to deserialize the data, the serializer throws an exception.

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

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

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

**Important: When to Register a Class Map**

You must register a class map *before* it's needed in your code. We recommend registering class maps before initializing a connection with MongoDB.

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:

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

### Omit Fields

You can prevent specified fields from being serialized by using the `UnmapMember()` method when registering a class map.

The following example shows how to create a class map to prevent the `Age` property from being serialized:

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

**Tip:**

To learn about how to set this behavior by using a field attribute, see the [Omit Fields](https://www.mongodb.com/docs/drivers/csharp/current/serialization/poco.md#std-label-csharp-poco-omit-fields) section of the POCOs guide.

### Ignore Extra Elements

When a BSON document is deserialized to a C# class, the .NET/C# Driver looks at the name of each field in the document and tries to find a matching property name in the class. By default, if a field in the document doesn't have a match in the class, the driver throws an exception.

You can choose to ignore any elements that do not have a matching class property by using the `BsonIgnoreExtraElements` attribute. This prevents the driver from throwing an exception, and maps any other fields that have matching class properties.

The following example shows how to add a `BsonIgnoreExtraElements` attribute to a class.

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

You can also ignore any extra elements when registering a class map:

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

### Identify Id Field

By default, the driver maps any public property named `Id`, `id`, or `_id` to the BSON `_id` field. To explicitly select the property to map to the `_id` field, use the `MapIdMember()` class map method.

The following code sample maps the `Identifier` property to the `_id` field:

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

#### String IDs

If you are using strings to represent your documement IDs, you can use the `IdMemberMap.SetSerializer()` class map method to serialize these values to `ObjectId` instances in MongoDB. This way, you can customize how your ID values are represented in your application while adhering to MongoDB best practices for ID management in the database.

The following example directs the driver to serialize string ID values as `ObjectId` values:

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

If you want the driver to generate valid 24-digit hex strings to use as your ID values, you can chain the `SetIdGenerator()` method to the `MapIdMember()` method and pass an instance of `StringObjectIdGenerator`:

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

To learn more about ID generators, see the [Specify an ID Generator](https://www.mongodb.com/docs/drivers/csharp/current/serialization/poco.md#std-label-csharp-poco-specify-id-gen) section of the POCOs guide.

#### GUID IDs

If your application uses GUIDs as unique identifiers in your documents, you can register a class map to specify how `Guid` values are serialized. By default, the driver uses the `GuidGenerator` type to generate a unique value for the ID property. You must specify the GUID representation by initializing a `GuidSerializer`.

The following code specifies the `Standard` GUID representation when registering the class map:

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

To learn more about serializing GUIDs, see the [GUIDs](https://www.mongodb.com/docs/drivers/csharp/current/serialization/guids.md#std-label-csharp-guids) guide.

## Mapping with Constructors

By default, the .NET/C# Driver automatically maps a class if the class has a no-argument constructor. This constructor can have any access modifier, including `private`. To have the driver use a constructor that accepts arguments, add the `BsonConstructor` attribute to the constructor. The driver then examines the type and maps the constructor arguments to the corresponding class properties or fields.

For the following `Person` class, the driver uses the constructor marked with the `BsonConstructor` attribute to create a class map. The `name` argument maps to the `Name` property and the `age` argument maps to the `Age` property.

```csharp
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;
    }
}
```

**Tip: Multiple BsonConstructor attributes**

If there is more than one constructor with the `BsonConstructor` attribute, the driver uses the constructor that has the most parameters with matching fields in the document.

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

```csharp
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.](https://www.mongodb.com/docs/drivers/csharp/current/serialization/poco.md#std-label-csharp-custom-serialization)

### Support Extra Elements

You can design your C# class to store any extra elements in your document that don't have matching class properties. To do this your class must have a `BsonDocument` type property to hold the extra elements.

The following code uses the `BsonExtraElements` attribute with the `ExtraElements` property to direct the driver to store extra elements:

```csharp
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;}
}
```

You can also support extra elements when initializing a class map as follows:

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

**Note:**

After the driver serializes a class with extra elements back to BSON, the extra elements may not be in the same order as they were in the original document.

### Dynamically Serialize Properties

You can use a method to determine whether to serialize a property. For the driver to automatically use the method when serializing, you must prefix the method name with `ShouldSerialize` followed by the name of the property that the method applies to. When the driver sees a method with this naming convention, it uses that method to determine whether to serialize properties that have the provided property name.

The following example creates a method that only serializes the `Age` property if its value is not equal to `0`. The driver does not serialize any properties whose values don't meet this requirement:

```csharp
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;
    }
}
```

You can also specify the method while registering a class map:

```csharp
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.](https://www.mongodb.com/docs/drivers/csharp/current/serialization/poco.md#std-label-csharp-poco)

## API Documentation

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

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

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