Introduction

In the MongoDB C# driver, “ignoring a field” can mean two different things during binding. You might want a property on your class to stay out of the stored document, or you might want the driver to tolerate extra fields that exist in MongoDB but do not exist on your class.

Ignore a Property on Your Model

If you have a property that should never be serialized or deserialized, decorate it with BsonIgnore:

1using MongoDB.Bson.Serialization.Attributes;
2
3public class Person
4{
5    public string Name { get; set; }
6
7    [BsonIgnore]
8    public string TemporaryDisplayName { get; set; }
9}

With that attribute, the driver does not write TemporaryDisplayName to MongoDB and does not try to populate it when reading a document back.

This is useful for computed values, UI-only fields, or data you derive elsewhere in the application.

Ignore Fields Only in Certain Cases

Sometimes you want to omit a field only when it has a default or null value. The driver provides targeted attributes for that:

1using MongoDB.Bson.Serialization.Attributes;
2
3public class Person
4{
5    public string Name { get; set; }
6
7    [BsonIgnoreIfNull]
8    public string Nickname { get; set; }
9
10    [BsonIgnoreIfDefault]
11    public int Age { get; set; }
12}

These attributes help reduce noise in stored documents while still allowing the property to participate in mapping when it has a meaningful value.

Ignore Extra Fields from the Document

A different problem appears when MongoDB documents contain fields that your C# class does not declare. By default, that can cause deserialization problems depending on how the mapping is configured.

To tell the driver to ignore unknown fields coming from the document, use BsonIgnoreExtraElements:

1using MongoDB.Bson.Serialization.Attributes;
2
3[BsonIgnoreExtraElements]
4public class Person
5{
6    public string Name { get; set; }
7}

Now a MongoDB document can contain fields such as legacyCode or lastSeenAt without breaking deserialization into Person.

This is especially useful during schema evolution, where old and new versions of documents may coexist.

Configure Ignoring in Class Maps

If you do not want to use attributes, you can configure the same behavior with a class map:

1using MongoDB.Bson.Serialization;
2
3BsonClassMap.RegisterClassMap<Person>(cm =>
4{
5    cm.AutoMap();
6    cm.SetIgnoreExtraElements(true);
7    cm.UnmapMember(p => p.TemporaryDisplayName);
8});

Class maps are helpful when you cannot modify the model type directly or when you want mapping rules centralized in one place.

Choose the Right Kind of Ignoring

It helps to separate the cases clearly:

• Use BsonIgnore when a class property should not participate in binding at all.
• Use BsonIgnoreIfNull or BsonIgnoreIfDefault when omission depends on the value.
• Use BsonIgnoreExtraElements when the MongoDB document contains fields your class should safely ignore.

These are related features, but they solve different problems.

Common Pitfalls

A common mistake is using BsonIgnore when the real issue is extra document fields. BsonIgnore affects a declared property on the class, not unknown fields present in MongoDB.

Another issue is forgetting that ignored properties are not round-tripped. If a field is marked with BsonIgnore, the driver will not persist it, so do not expect it to reappear after a save and reload cycle.

People also mix attribute-based mapping and class-map configuration without realizing one may override the other depending on setup order. Keep mapping rules consistent.

Finally, be careful during schema migrations. Ignoring extra elements is useful for compatibility, but it can also hide data that your application should eventually understand explicitly.

Summary

• In the MongoDB C# driver, ignored properties and ignored extra document fields are different concerns.
• Use BsonIgnore to exclude a known class property from binding.
• Use BsonIgnoreIfNull or BsonIgnoreIfDefault for conditional omission.
• Use BsonIgnoreExtraElements when documents contain fields your class does not model.
• Class maps provide the same controls when attributes are not a good fit.