Community

Markus Wildgruber

Managing Director/Cloud Architect, sevantage software GmbH

> Starting out with MongoDB and C#? These tips will help you get your class maps right from the beginning to support your desired schema.

When starting my first projects with MongoDB and C# several years ago, what captivated me the most was how easy it was to store plain old CLR objects (POCOs) in a collection without having to create a static relational structure first and maintaining it painfully over the course of development.  

Though MongoDB and C# have their own set of data types and naming conventions, the [MongoDB C# Driver](https://www.mongodb.com/docs/drivers/csharp/current/#mongodb-c--driver) connects the two in a very seamless manner. At the center of this, [class maps](https://www.mongodb.com/docs/drivers/csharp/current/fundamentals/serialization/class-mapping/) are used to describe the details of the mapping.  

This post shows how to fine-tune the mapping in key areas and offers solutions to common scenarios.

## Automatic mapping

Even if you don't define a class map explicitly, the driver will create one as soon as the class is used for a collection. In this case, the properties of the POCO are mapped to elements in the BSON document based on the name. The driver also tries to match the property type to the BSON type of the element in MongoDB.

Though automatic mapping of a class will make sure that POCOs can be stored in a collection easily, tweaking the mapping is rewarded by better memory efficiency and enhanced query performance. Also, if you are working with existing data, customizing the mapping allows POCOs to follow C# and .NET naming conventions without changing the schema of the data in the collection.

## Declarative vs. imperative mapping

Adjusting the class map can be as easy as adding attributes to the declaration of a POCO (declarative mapping). These attributes are used by the driver when the class map is auto-mapped. This happens when the class is first used to access data in a collection:

```csharp
public class BlogPost
{
  // ...
  [BsonElement("title")]
  public string Title { get; set; } = string.Empty;
  // ...
}
```

The above sample shows how the `BsonElement` attribute is used to adjust the name of the `Title` property in a document in MongoDB:

```BSON
{
  // ...
  "title": "Blog post title",
  // ...
}
```

However, there are scenarios when declarative mapping is not applicable: If you cannot change the POCOs because they are defined in a third-party libary or if you want to separate your POCOs from MongoDB-related code parts, there also is the option to define the class maps imperatively by calling methods in code:

```csharp
BsonClassMap.RegisterClassMap<BlogPost>(cm =>
{
  cm.AutoMap();
  cm.MapMember(x => x.Title).SetElementName("title");
});
```

The code above first performs the auto-mapping and then includes the `Title` property in the mapping as an element named `title` in BSON, thus overriding the auto-mapping for the specific property.

One thing to keep in mind is that the class map needs to be registered before the driver starts the automatic mapping process for a class. It is a good idea to include it in the bootstrapping process of the application.

This post will use declarative mapping for better readability but all of the adjustments can also be made using imperative mapping, as well. You can find an imperative class map that contains all the samples at the end of the post. 
## Adjusting property names

Whether you are working with existing data or want to name properties differently in BSON for other reasons, you can use the `BsonElement("specificElementName")` attribute introduced above. This is especially handy if you only want to change the name of a limited set of properties.  

If you want to change the naming scheme in a widespread fashion, you can use a convention that is applied when auto-mapping the classes. The driver offers a number of conventions out-of-the-box (see the namespace [MongoDB.Bson.Serialization.Conventions](https://mongodb.github.io/mongo-csharp-driver/2.22/html/N_MongoDB_Bson_Serialization_Conventions.htm)) and offers the flexibility to create custom ones if those are not sufficient.  

An example is to name the POCO properties according to C# naming guidelines in Pascal case in C#, but name the elements in camel case in BSON by adding the [CamelCaseElementNameConvention](https://mongodb.github.io/mongo-csharp-driver/2.22/html/T_MongoDB_Bson_Serialization_Conventions_CamelCaseElementNameConvention.htm): 

```csharp
var pack = new ConventionPack();
pack.Add(new CamelCaseElementNameConvention());
ConventionRegistry.Register(
  "Camel Case Convention",
  pack, 
  t => true);
```

Please note the predicate in the last parameter. This can be used to fine-tune whether the convention is applied to a type or not. In our sample, it is applied to all classes.   
The above code needs to be run before auto-mapping takes place. You can still apply a `BsonElement` attribute here and there if you want to overwrite some of the names.

## Using ObjectIds as identifiers

MongoDB uses [ObjectIds](https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-objectid) as identifiers for documents by default for the “_id” field. This is a data type that is unique to a very high probability and needs 12 bytes of memory. If you are working with existing data, you will encounter ObjectIds for sure. Also, when setting up new documents, ObjectIds are the preferred choice for identifiers. In comparison to GUIDs (UUIDs), they require less storage space and are ordered so that identifiers that are created later receive higher values.

In C#, properties can use `ObjectId` as their type. However, using `string` as the property type in C# simplifies the handling of the identifiers and increases interoperability with other frameworks that are not specific to MongoDB (e.g. OData).  

In contrast, MongoDB should serialize the identifiers with the specific BSON type ObjectId to reduce storage size. In addition, performing a binary comparison on ObjectIds is much safer than comparing strings as you do not have to take letter casing, etc. into account.

```csharp
public class BlogPost
{
  [BsonRepresentation(BsonType.ObjectId)]
  public string Id { get; set; } = ObjectId.GenerateNewId().ToString();
  // ...
  [BsonRepresentation(BsonType.ObjectId)]
  public ICollection<string> TopComments { get; set; } = new List<string>();
}
```

By applying the `BsonRepresentation` attribute, the `Id` property is serialized as an `ObjectId` in BSON. Also, the array of identifiers in `TopComments` also uses ObjectIds as their data type for the array elements: 

```BSON
{ 
  "_id" : ObjectId("6569b12c6240d94108a10d20"), 
  // ...
  "TopComments" : [
    ObjectId("6569b12c6240d94108a10d21"), 
    ObjectId("6569b12c6240d94108a10d22")
  ] 
}
```
## Serializing GUIDs in a consistent way

While `ObjectId` is the default type of identifier for MongoDB, GUIDs or UUIDs are a data type that is used for identifying objects in a variety of programming languages. In order to store and query them efficiently, using a binary format instead of strings is also preferred. 

In the past, GUIDs/UUIDs have been stored as BSON type binary of subtype 3; drivers for different programming environments serialized the value differently. Hence, reading GUIDs with the C# driver that had been serialized with a Java driver did not yield the same value. To fix this, the new binary subtype 4 was introduced by MongoDB. GUIDs/UUIDs are then serialized in the same way across drivers and languages. 

To provide the flexibility to both handle existing values and new values on a property level, the MongoDB C# Driver introduced a new way of handling GUIDs. This is referred to as `GuidRepresentationMode.V3`. For backward compatibility, when using Version 2.x of the MongoDB C# Driver, the GuidRepresentationMode is V2 by default (resulting in binary subtype 3). This is set to change with MongoDB C# Driver version 3. It is a good idea to opt into using V3 now and specify the subtype that should be used for GUIDs on a property level. For new GUIDs, subtype 4 should be used. 

This can be achieved by running the following code before creating the client: 

```csharp
BsonDefaults.GuidRepresentationMode 
= GuidRepresentationMode.V3;
```

Keep in mind that this setting requires the representation of the GUID to be specified on a property level. Otherwise, a `BsonSerializationException` will be thrown informing you that "GuidSerializer cannot serialize a Guid when GuidRepresentation is Unspecified." To fix this, add a `BsonGuidRepresentation` attribute to the property: 

```csharp
[BsonGuidRepresentation(GuidRepresentation.Standard)]
public Guid MyGuid { get; set; } = Guid.NewGuid();
```

There are various settings available for `GuidRepresentation`. For new GUIDs, `Standard` is the preferred value, while the other values (e.g., `CSharpLegacy`) support the serialization of existing values in binary subtype 3. 

For a detailed overview, see the [documentation of the driver](https://www.mongodb.com/docs/drivers/csharp/current/fundamentals/serialization/guid-serialization/). 

## Processing extra elements

Maybe you are working with existing data and only some part of the elements is relevant to your use case. Or you have older documents in your collection that contain elements that are not relevant anymore. Whatever the reason, you want to keep the POCO minimal so that it only comprises the relevant properties.  

By default, the MongoDB C# Driver is strict and raises a `FormatException` if it encounters elements in a BSON document that cannot be mapped to a property on the POCO: 

```"Element '[...]' does not match any field or property of class [...]."```
 Those elements are called "extra elements."

One way to handle this is to simply ignore extra elements by applying the `BsonIgnoreExtraElements` attribute to the POCO: 

```csharp
[BsonIgnoreExtraElements]
public class BlogPost 
{
  // ...
}
```

If you want to use this behavior on a large scale, you can again register a convention: 

```csharp
var pack = new ConventionPack();
pack.Add(new IgnoreExtraElementsConvention(true));
ConventionRegistry.Register(
  "Ignore Extra Elements Convention",
  pack, 
  t => true);
```
Be aware that if you use _replace_ when storing the document, extra properties that C# does not know about will be lost. 

On the other hand, MongoDB's flexible schema is built for handling documents with different elements. If you are interested in the extra properties or you want to safeguard for a replace, you can add a dictionary to your POCO and mark it with a `BsonExtraElements` attribute. The dictionary is filled with the content of the properties upon deserialization: 

```csharp
public class BlogPost
{
  // ...
  [BsonExtraElements()]
  public IDictionary<string, object> ExtraElements { get; set; } = new Dictionary<string, object>();
}
```
Even when replacing a document that contains an extra-elements-dictionary, the key-value pairs of the dictionary are serialized as elements so that their content is not lost (or even updated if the value in the dictionary has been changed). 

## Serializing calculated properties

Pre-calculation is key for great query performance and is a common pattern when working with MongoDB. In POCOs, this is supported by adding read-only properties, e.g.: 

```csharp
public class BlogPost
{
  // ...
  public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
  public DateTime? UpdatedAt { get; set; }
  public DateTime LastChangeAt => UpdatedAt ?? CreatedAt;
}
```

By default, the driver excludes read-only properties from serialization. This can be fixed easily by applying a `BsonElement` attribute to the property — you don't need to change the name: 

```csharp
public class BlogPost
{
  // ...
  public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
  public DateTime? UpdatedAt { get; set; }
  [BsonElement()]
  public DateTime LastChangeAt => UpdatedAt ?? CreatedAt;
}
```

After this change, the read-only property is included in the document and it can be used in indexes and queries: 

```BSON
{ 
  // ...
  "CreatedAt" : ISODate("2023-12-01T12:16:34.441Z"), 
  "UpdatedAt" : null, 
  "LastChangeAt" : ISODate("2023-12-01T12:16:34.441Z") 
}
```
## Custom serializers

Common scenarios are very well supported by the MongoDB C# Driver. If this is not enough, you can create a [custom serializer](https://www.mongodb.com/docs/drivers/csharp/current/fundamentals/serialization/#custom-serializers) that supports your specific scenario.  

Custom serializers can be used to handle documents with different data for the same element. For instance, if some documents store the year as an integer and others as a string, a custom serializer can analyze the BSON type during deserialization and read the value accordingly. 

However, this is a last resort that you will rarely need to use as the existing options offered by the MongoDB C# Driver cover the vast majority of use cases. 

## Conclusion

As you have seen, the MongoDB C# Driver offers a lot of options to tweak the mapping between POCOs and BSON documents. POCOs can follow C# conventions while at the same time building upon a schema that offers good query performance and reduced storage consumption. 

If you have questions or comments, join us in the [MongoDB Developer Community](https://www.mongodb.com/community/forums/)!

### Appendix: sample for imperative class map

```csharp
BsonClassMap.RegisterClassMap<BlogPost>(cm =>
{
  // Perform auto-mapping to include properties 
  // without specific mappings
  cm.AutoMap();
  // Serialize string as ObjectId
  cm.MapIdMember(x => x.Id)
    .SetSerializer(new StringSerializer(BsonType.ObjectId));
  // Serialize ICollection<string> as array of ObjectIds
  cm.MapMember(x => x.TopComments)
    .SetSerializer(
       new IEnumerableDeserializingAsCollectionSerializer<ICollection<string>, string, List<string>>(
         new StringSerializer(BsonType.ObjectId)));
  // Change member name
  cm.MapMember(x => x.Title).SetElementName("title");
  // Serialize Guid as binary subtype 4
  cm.MapMember(x => x.MyGuid).SetSerializer(new GuidSerializer(GuidRepresentation.Standard));
  // Store extra members in dictionary
  cm.MapExtraElementsMember(x => x.ExtraElements);
  // Include read-only property
  cm.MapMember(x => x.LastChangeAt);
});
```






Starting out with MongoDB and C#? These tips will help you get your class maps right from the beginning to support your desired schema.

How to Set Up MongoDB Class Maps for C# for Optimal Query Performance and Storage Size

Among the good news of MongoDB.local NYC '24, was the announcement that MongoDB Entity Framework Core Provider has been made [globally available](https://www.mongodb.com/blog/post/mongodb-provider-entity-framework-core-now-generally-available). The provider integrates with Entity Framework and empowers .NET developers to easily access data in MongoDB databases with a well known framework.  

This post shows how you can set up the Provider in a C# project and build an API with ASP.NET Core that offers an OData compatible endpoint. For those new to [OData](https://www.odata.org/), this is a protocol that is used to build queryable REST APIs. User interfaces can access these APIs and use them to provide tabular views that offer a rich set of user interactions, like filtering, sorting or paging. As OData is an open standard, there is a wide variety of tools that can access OData compatible endpoints, e.g. Microsoft Excel or Microsoft Power BI. 

If you want to follow along with the samples in this post, we create an endpoint that queries the movies in the sample_flix-database. The easiest way to get an instance of this sample database is to [load the sample data in a MongoDB Atlas cluster](https://www.mongodb.com/docs/atlas/sample-data/). If you do not have a cluster already, you can set up a free MongoDB Atlas M0 cluster (see this [link](https://www.mongodb.com/docs/atlas/tutorial/deploy-free-tier-cluster/) for a guide). 

While this post will use a newly created ASP.NET Core Web API project, it is perfectly fine to add OData to offer the endpoints in addition to existing REST endpoints. When creating a new project, you might want to enable OpenAPI support for an easy way to test the API later on. Also, the new project should use controllers instead of a minimal API. 

![Additional information wizard showing default values](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt0d3de225540ded04/6659ba379518af99ef667d57/Additional_Info_Wizard.png)

# Create the Entity Framework DbContext

After setting up the ASP.NET Core project, we will first define the Entity Framework DbContext and then set it up with the MongoDB Entity Framework Core Provider. 

The first step is to add the MongoDB Entity Framework Core Provider package to the project either through the UI or the `dotnet` CLI: 

    dotnet add package MongoDB.EntityFrameworkCore

Then we define the entity class that contains the properties that we want to read from the database: 

```csharp
// requires using MongoDB.Bson;
public class Movie
{
    public string Id { get; set; } = ObjectId.GenerateNewId().ToString();
    public string Title { get; set; } = string.Empty;
    public string? Plot { get; set; }
    public IEnumerable<string>? Genres { get; set; }
    public IEnumerable<string>? Cast { get; set; }
    // additional properties as required
}
```

> Some of the properties (e.g. `Plot`) are nullable reference types. This asserts that missing values in the database do not result in an error when reading the documents. 

The next step is to set up the DbContext and add the configuration for the entity. This includes binding the entity to a collection and, as we are working with existing documents that follow a different naming convention, mapping the property names of the document to the ones of the .NET POCO: 

```csharp
// requires using Microsoft.EntityFrameworkCore;
// requires using MongoDB.Bson;
// requires using MongoDB.EntityFrameworkCore.Extensions;

public class MflixDbContext : DbContext
{
    public MflixDbContext(DbContextOptions options)
        : base(options)
    {
    }

    public DbSet<Movie> Movies { get; init; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        var movieEntity = modelBuilder.Entity<Movie>();
        movieEntity.ToCollection("movies");
        movieEntity.Property(x => x.Id)
            .HasElementName("_id")
            .HasConversion<ObjectId>();
        movieEntity.Property(x => x.Title).HasElementName("title");
        movieEntity.Property(x => x.Plot).HasElementName("plot");
        movieEntity.Property(x => x.Genres).HasElementName("genres");
        movieEntity.Property(x => x.Cast).HasElementName("cast");
    }
}
```

The `Id` property deserves special attention: in the MongoDB document, the `_id` property is stored as an ObjectId. In an OData interface, using strings instead of an `ObjectId` as the identifier value is much easier. By adding value conversion, we can have the best of both worlds: ObjectIds in MongoDB and strings in .NET. 

To finalize the set up of the MongoDB Entity Framework Core Provider, we register the client, database, and `MflixDbContext` in the IoC container: 

```csharp
// requires using Microsoft.EntityFrameworkCore;
// requires using MongoDB.Driver;
// requires using MongoDBEFODataVerify;

builder.Services.AddSingleton<IMongoClient>(prov =>
{
    // Retrieve connection string from configuration
    return new MongoClient("<your MongoDB connection string>");
});
builder.Services.AddSingleton(prov =>
{
    var client = prov.GetRequiredService<IMongoClient>();
    // Retrieve database name from configuration
    return client.GetDatabase("sample_mflix");
});
builder.Services.AddDbContext<MflixDbContext>((prov, options) =>
{
    var database = prov.GetRequiredService<IMongoDatabase>();
    options.UseMongoDB(
        database.Client, 
        database.DatabaseNamespace.DatabaseName);
});
```

If you are only using Entity Framework, it would be sufficient to register `MflixDbContext` and create the client in the factory method. The above sample code registers the client and database instance separately so that you can inject them independently if required. 

With the `DbContext` set up, we could also use controller scaffolding in order to generate the code for REST controllers if needed. However, for the sake of this post we will now create an OData endpoint from scratch. 

# Add OData to the project

The first step when adding OData to a project is to reference the `Microsoft.AspNetCore.OData` package, either through the UI or using the `dotnet` CLI: 

    dotnet add package Microsoft.AspNetCore.OData

Next, we add a method that defines the EDM model for the OData interface in `Program.cs`: 

```csharp
// requires using Microsoft.OData.Edm;
// requires using Microsoft.OData.ModelBuilder;

IEdmModel GetEdmModel()
{
    var model = new ODataConventionModelBuilder();
    model.EnableLowerCamelCase();
    model.EntitySet<Movie>("Movies");
    return model.GetEdmModel();
}
```

`EnableLowerCamelCase` changes the naming convention of the properties to start with a lowercase character. This matches the behavior of JSON serialization in a standard REST API. 

We then register the OData components with the IoC container by adding the following code in `Program.cs`: 

```csharp
// requires using Microsoft.OData;

// This should be already in the code
builder.Services
    .AddControllers()
// This is new
    .AddOData(options => options
        .Select()
        .Filter()
        .OrderBy()
        .Count()
        .SetMaxTop(100)
        .AddRouteComponents("odata", GetEdmModel()));
```

The code above enables various OData operations and restricts the maximum number of entities a client can request to prevent an overly large result set. 

Lastly, we add a controller that provides the OData endpoint for our query. The name of the controller should be `MoviesController` to match the registration of the entity set in `GetEdmModel`: 

```csharp
// requires using Microsoft.AspNetCore.OData.Query;
// requires using Microsoft.AspNetCore.OData.Routing.Controllers;

public class MoviesController : ODataController
{
    private readonly MflixDbContext _dbContext;

    public MoviesController(MflixDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    [EnableQuery(
        PageSize = 1000, 
        AllowedOrderByProperties = "title, plot")]  
    public IQueryable<Movie> Get()
    {
        return _dbContext.Movies;
    }
}
```

We inject an instance of `MflixDbContext` into the controller to retrieve the movies and mark the `Get` method with the `EnableQuery` attribute. The `PageSize` property allows us to set the maximum number of results sent to the client. Using `AllowedOrderByProperties` restricts the properties that can be used in sort operations. 

> The name must match the name that is serialized - lower camel case in our sample as we called `EnableLowerCamelCase` in `GetEdmModel` earlier. There are various other options that you can use to adjust the behavior of the query endpoint. Please see the [ASP.NET Core OData documentation](https://learn.microsoft.com/en-us/odata/webapi-8/fundamentals/query-options) for details. 

# Test the endpoint

Now we are ready to test the OData endpoint and start it in the debugger. If you have enabled OpenAPI and Swagger UI in your project, you can use Swagger UI for a simple test. This is enough to check basic readiness of the endpoint and serves as a good starting point. 

For more sophisticated requests, either enter the OData URL in a browser or use a tool like Postman or `curl` with OData URLs. 

A simple request to `https://localhost:\<YOUR PORT\>/odata/Movies` should return 10 movies in the following format: 

```JSON
{
    "@odata.context": "https://localhost:7104/odata/$metadata#Movies",
    "value": [
        {
            "id": "573a1390f29313caabcd4135",
            "title": "Blacksmith Scene",
            "plot": "Three men hammer on an anvil...",
            "genres": [
                "Short"
            ],
            "cast": [
                "Charles Kayser",
                "John Ott"
            ]
        },
        // 999 more results
    ],
    "@odata.nextLink": "https://localhost:7104/odata/Movies?$skip=10"
}
```

In order to make use of OData features like paging and filtering, you can also try the following requests: 

- Filter by title:   
  `https://localhost:\<YOUR PORT\>/odata/Movies?$filter=title eq 'The Godfather'`
- Filter by part of title - case insensitive:  
  `https://localhost:\<YOUR PORT\>/odata/Movies?$filter=contains(tolower(title), 'godfather')`
- Paging with `$skip`, `$top` and `$count`:   
  `https://localhost:\<YOUR PORT\>/odata/Movies?$count=true&$top=10&$skip=10`
- Sorting with `$orderBy`:   
  `https://localhost:\<YOUR PORT\>/odata/Movies?$orderBy=title ASC`

# OData using MongoDB C# Driver

What if you already have an API and are using MongoDB C# Driver without Entity Framework? Plain and simple, all you need for OData to work is an `IQueryable<T>`. 

This can be provided easily by `IMongoCollection<T>.AsQueryable()` so that we could also build the OData endpoint like this: 

```csharp
// requires using Microsoft.AspNetCore.OData.Query;
// requires using Microsoft.AspNetCore.OData.Routing.Controllers;
// requires using MongoDB.Driver;

public class MoviesController : ODataController
{
    private readonly IMongoCollection<Movie> _collMovies;

    public MoviesController(IMongoDatabase db)
    {
        _collMovies = db.GetCollection<Movie>("movies");
    }

    [EnableQuery(
        PageSize = 1000, 
        AllowedOrderByProperties = "title, plot")]
    public IQueryable<Movie> Get()
    {
        return _collMovies.AsQueryable();
    }
}
```

Please note that you also need to configure the mapping for the `Movie` class either by adding attributes or defining the class map imperatively. 

# Advanced query options

Up to now, we have built an OData endpoint that supports basic options for filtering, sorting and paging with the Microsoft.AspNetCore.OData package. Unfortunately, this package does not support `$select` and `$expand` in your requests. If you want to go one step further and also add support for these operations, you need to rely on a package provided by MongoDB and reference **MongoDB.AspNetCore.OData** instead of the Microsoft package. All you need to do is replace `EnableQuery` with `MongoEnableQuery` and your endpoint will support these operations.

```csharp
// requires using Microsoft.AspNetCore.OData.Routing.Controllers;
// requires using MongoDB.AspNetCore.OData.Query;
// requires using MongoDB.Driver;

public class MoviesController : ODataController
{
    private readonly IMongoCollection<Movie> _collMovies;

    public MoviesController(IMongoDatabase db)
    {
        _collMovies = db.GetCollection<Movie>("movies");
    }

    // Change this from EnableQuery to MongoEnableQuery
    [MongoEnableQuery(
        PageSize = 1000, 
        AllowedOrderByProperties = "title, plot")]
    public IQueryable<Movie> Get()
    {
        return _collMovies.AsQueryable();
    }
}
```

At the time of this writing, you need to follow the approach described in the section OData using MongoDB C# Driver above and cannot use a `DbSet<T>` provided by MongoDB Entity Framework Core Provider. 

For details on the package see this [repository](https://github.com/mongodb/mongo-aspnetcore-odata) on Github.

# Summary

In this post we showed how easy it is to add powerful query options to your API, with an OData endpoint that builds on Entity Framework and MongoDB. This API can be used to provide rich query options in the UI of your apps or can be accessed from popular tools like Microsoft Excel. As both frameworks are very powerful and offer a lot of options, be sure to check out the documentation on [MongoDB Entity Framework Core Provider](https://www.mongodb.com/docs/entity-framework/current/) and [ASP.NET Core OData](https://learn.microsoft.com/en-us/odata/webapi-8/overview). 

Do you already use OData or MongoDB Entity Framework Core Provider? Let us know in the [forums](https://community.mongodb.com).


Learn how to easily add OData support to a new or existing ASP.NET Core project with the new EF Core Provider

Query Your Data With ASP.NET Core, OData, and the MongoDB Entity Framework Core Provider

In comparison to relational database management systems (RDBMS), MongoDB's flexible schema is a huge step forward when handling object-oriented data. These structures often make use of polymorphism where common base classes contain the shared fields that are available for all classes in the hierarchy; derived classes add the fields that are relevant only to the specific objects. An example might be to have several types of vehicles, like cars and motorcycles, that have some fields in common, but each type also adds some fields that make only sense if used for a type: 

![An entity class diagram showing a vehicle type and then car and motorcycle classes that extend it](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blte9072d1e9c252d99/6630bb46ba17b050b3cb6c29/Screenshot_2024-04-30_103434.png)

For RDBMS, storing an object hierarchy is a challenge. One way is to store the data in a table that contains all fields of all classes, though for each row, only a subset of fields is needed. Another approach is to create a table for the base class that contains the shared fields and add a table for each derived class that stores the columns for the specific type and references the base table. Neither of these approaches is optimal in terms of storage and when it comes to querying the data. 

However, with MongoDB's flexible schema, one can easily store documents in the same collection that do only share some but not all fields. This article shows how the [MongoDB C# driver](https://www.mongodb.com/docs/drivers/csharp/current/) makes it easy to use this for storing class hierarchies in a very natural way. 

Example use cases include storing metadata for various types of documents, e.g., offers, invoices, or other documents related to business partners in a collection. Common fields could be a document title, a summary, the date, a vector embedding, and the reference to the business partner, whereas an invoice would add fields for the line items and totals but would not add the fields for a project report. 

Another possible use case is to serve both an overview and a detail view from the same collection. We will have a closer look at how to implement this in the summary of this article. 

# Basics

When accessing a collection from C#, we use an object that implements `IMongoCollection<T>` interface. This object can be created like this: 

```csharp
var vehiclesColl = db.CreateCollection<Vehicle>("vehicles");
```

When serializing or deserializing documents, the type parameter `T` and the actual type of the object provide the MongoDB C# driver with a hint on how to map the BSON representation to a C# class and vice versa. If only documents of the same type reside in the collection, the driver uses the class map of the type. 

However, to be able to handle class hierarchies correctly, the driver needs more information. This is where the *type discriminator* comes in. When storing a document of a derived type in the collection, the driver adds a field named `_t` to the document that contains the name of the class, e.g.:

```csharp
await vehiclesColl.InsertOneAsync(new Car());
```

leads to the following document structure: 

```JSON
{
  "_id": ObjectId("660d7d43e042f8f6f2726f6a"),
  "_t": "Car",
  // ... fields for vehicle 
  // ... fields specific to car
}
```

When deserializing the document, the value of the `_t` field is used to identify the type of the object that is to be created. 

Though this works out of the box without specific configuration, it is advised to support the driver by specifying the class hierarchy explicitly by using the `BsonKnownTypes` attribute, if you are using declarative mapping: 

```csharp
[BsonKnownTypes(typeof(Car), typeof(Motorcycle))]
public abstract class Vehicle
{
    // ...
}
```

If you configure the class maps imperatively, just add a class map for each type in the hierarchy to reach the same effect. 

By default, only the name of the class is used as value for the type discriminator. Especially if the hierarchy spans several levels and you want to query for any level in the hierarchy, you should store the hierarchy as an array in the type discriminator by using the `BsonDiscriminator` attribute: 

```csharp
[BsonDiscriminator(RootClass = true)]
[BsonKnownTypes(typeof(Car), typeof(Motorcycle))]
public abstract class Vehicle
{
    // ...
}
```

This applies a different discriminator convention to the documents and stores the hierarchy as an array:

```JSON
{
  "_id": ObjectId("660d81e5825f1c064024a591"),
  "_t": [
    "Vehicle",
    "Car"
  ],
  // ...
}
```

For additional details on how to configure the class maps for polymorphic objects, see the [documentation](https://www.mongodb.com/docs/drivers/csharp/current/fundamentals/serialization/polymorphic-objects/) of the driver. 

# Querying collections with polymorphic documents

When reading objects from a collection, the MongoDB C# driver uses the type discriminator to identify the matching type and creates a C# object of the corresponding class. The following query might yield both `Car` and `Motorcycle` objects: 

```csharp
var vehiclesColl = db.GetCollection<Vehicle>("vehicles");
var vehicles = (await vehiclesColl.FindAsync(FilterDefinition<Vehicle>.Empty))
    .ToEnumerable();
```

If you are only interested in documents of a specific type, you can create another instance of `IMongoCollection<T>` that returns only these: 

```csharp
var carsColl = vehiclesColl.OfType<Car>();
var cars = (await carsColl.FindAsync(FilterDefinition<Car>.Empty))
    .ToEnumerable();
```

This new collection instance respects the corresponding type discriminator whenever an operation is performed. The following statement removes only `Car` documents from the collection but keeps the `Motorcycle` documents as they are: 

```csharp
await carsColl.DeleteManyAsync(FilterDefinition<Car>.Empty);
```

If you are using the LINQ provider brought by the MongoDB C# driver, you can also use the LINQ `OfType<T>` extension method to only retrieve the `Car` objects: 

```csharp
var cars = vehiclesColl.AsQueryable().OfType<Car>();
```

# Serving multiple views from a single collection

As promised before, we now take a closer look at a use case for polymorphism: Let's suppose we are building a system that supports monitoring sensors that are distributed over several sites. The system should provide an overview that lists all sites with their name and the last value that was reported for the site along with a timestamp. When selecting a site, the system shows detailed information for the site that consists of all the data on the overview and also lists the sensors that are located at the specific site with their last value and its timestamp. 

This can be depicted by creating a base class for the documents that contains the id of the site, a name to identify the document, and the last measurement, if available. A derived class for the site overview adds the site address; another one for the sensor detail contains the location of the sensor: 

```csharp
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;

public abstract class BaseDocument
{
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; } = ObjectId.GenerateNewId().ToString();

    [BsonRepresentation(BsonType.ObjectId)]
    public string SiteId { get; set; } = ObjectId.GenerateNewId().ToString();

    public string Name { get; set; } = string.Empty;

    public Measurement? Last { get; set; }
}

public class Measurement
{
    public int Value { get; set; }

    public DateTime Timestamp { get; set; }
}

public class Address
{
  // ...
}

public class SiteOverview : BaseDocument
{
    public Address Address { get; set; } = new();
}

public class SensorDetail : BaseDocument
{
    public string Location { get; set; } = string.Empty;
}
```

When ingesting new measurements, both the site overview and the sensor detail are updated (for simplicity, we do not use a multi-document transaction): 

```csharp
async Task IngestMeasurementAsync(
    IMongoCollection<BaseDocument> overviewsColl,
    string sensorId,
    int value)
{
    var measurement = new Measurement()
    {
        Value = value,
        Timestamp = DateTime.UtcNow
    };
    var sensorUpdate = Builders<SensorDetail>
        .Update
        .Set(x => x.Last, measurement);
    var sensorDetail = await overviewsColl
        .OfType<SensorDetail>()
        .FindOneAndUpdateAsync(
            x => x.Id == sensorId,
            sensorUpdate,
            new() { ReturnDocument = ReturnDocument.After });
    if (sensorDetail != null)
    {
        var siteUpdate = Builders<SiteOverview>
            .Update
            .Set(x => x.Last, measurement);
        var siteId = sensorDetail.SiteId;
        await overviewsColl
            .OfType<SiteOverview>()
            .UpdateOneAsync(x => x.SiteId == siteId, siteUpdate);
    }
}
```

Above sample uses `FindAndUpdateAsync` to both update the sensor detail document and also retrieve the resulting document so that the site id can be determined. If the site id is known beforehand, a simple update can also be used. 

When retrieving the documents for the site overview, the following code returns all the relevant documents: 

```csharp
var siteOverviews = (await overviewsColl
        .OfType<SiteOverview>()
        .FindAsync(FilterDefinition<SiteOverview>.Empty))
    .ToEnumerable();
```

When displaying detailed data for a specific site, the following query retrieves all documents for the site by its id in a single request: 

```csharp 
var siteDetails = await (await overviewsColl
    .FindAsync(x => x.SiteId == siteId))
    .ToListAsync();
```

The result of the query can contain objects of different types; you can use the LINQ `OfType<T>` extension method on the list to discern between the types, e.g., when building a view model. 

This approach allows for efficient querying from different perspectives so that central views of the application can be served with minimum load on the server. 

# Summary

Polymorphism is an important feature of object-oriented languages and there is a wide range of use cases for it. As you can see, the MongoDB C# driver provides a solid bridge between object orientation and the MongoDB flexible document schema. If you want to dig deeper into the subject from a data modeling perspective, be sure to check out the [polymorphic pattern](https://www.mongodb.com/developer/products/mongodb/polymorphic-pattern/) part of the excellent series "Building With Patterns" on the MongoDB Developer Center. 

An article discussing when and how to use polymorphism in a C# application using the MongoDB C# Driver.

Markus Wildgruber

Content by Markus Wildgruber

How to Set Up MongoDB Class Maps for C# for Optimal Query Performance and Storage Size

Query Your Data With ASP.NET Core, OData, and the MongoDB Entity Framework Core Provider

Using Polymorphism with MongoDB and C#