Using LINQ to Query MongoDB in a .NET Core Application

If you’ve been keeping up with my series of tutorials around .NET Core and MongoDB, you’ll likely remember that we explored using the Find operator to query for documents as well as an aggregation pipeline. Neither of these previously explored subjects are too difficult, but depending on what you’re trying to accomplish, they could be a little messy. Not to mention, they aren’t necessarily “the .NET way” of doing business.

This is where LINQ comes into the mix of things!

With Language Integrated Queries (LINQ), we can use an established and well known C# syntax to work with our MongoDB documents and data.

In this tutorial, we’re going to look at a few LINQ queries, some as a replacement to simple queries using the MongoDB Query API and others as a replacement to more complicated aggregation pipelines.

The requirements

To be successful with this tutorial, you should already have the following ready to go:

• .NET Core 6+
• MongoDB Atlas, the free tier or better

When it comes to MongoDB Atlas, you’ll need to have a cluster deployed and properly configured with user roles and network rules. If you need help with this, take a look at my previous tutorial on the subject. You will also need the sample datasets installed.

While this tutorial is part of a series, you don’t need to have read the others to be successful. However, you’d be doing yourself a favor by checking out the other ways you can do business with .NET Core and MongoDB.

Creating a new .NET Core console application with the CLI

To keep this tutorial simple and easy to understand, we’re going to create a new console application and work from that.

Execute the following from the CLI to create a new project that is ready to go with the MongoDB driver:

dotnet new console -o MongoExample
cd MongoExample
dotnet add package MongoDB.Driver

For this tutorial, our MongoDB Atlas URI string will be stored as an environment variable on our computer. Depending on your operating system, you can do something like this:

export ATLAS_URI="YOUR_ATLAS_URI_HERE"

The Atlas URI string can be found in your MongoDB Atlas Dashboard after clicking the “Connect” button and choosing your programming language.

Open the project’s Program.cs file and add the following C# code:

using MongoDB.Bson;
using MongoDB.Driver;
using MongoDB.Driver.Linq;

MongoClientSettings settings = MongoClientSettings.FromConnectionString(
    Environment.GetEnvironmentVariable("ATLAS_URI")
);

settings.LinqProvider = LinqProvider.V3;

MongoClient client = new MongoClient(settings);

In the above code, we are explicitly saying that we want to use LINQ Version 3 rather than Version 2, which is the default in MongoDB. While you can accomplish many LINQ-related tasks in MongoDB with Version 2, you’ll get a much better experience with Version 3.

Writing MongoDB LINQ queries in your .NET Core project

We’re going to take it slow and work our way up to bigger and more complicated queries with LINQ.

In case you’ve never seen the “sample_mflix” database that is part of the sample datasets that MongoDB offers, it’s a movie database with several collections. We’re going to focus strictly on the “movies” collection which has documents that look something like this:

{
    "_id": ObjectId("573a1398f29313caabceb515"),
    "title": "Batman",
    "year": 1989,
    "rated": "PG-13",
    "runtime": 126,
    "plot": "The Dark Knight of Gotham City begins his war on crime with his first major enemy being the clownishly homicidal Joker.",
    "cast": [ "Michael Keaton", "Jack Nicholson", "Kim Basinger" ]
}

There are quite a bit more fields to each of the documents in that collection, but the above fields are enough to get us going.

To use LINQ, we’re going to need to create mapped classes for our collection. In other words, we won’t want to be using BsonDocument when writing our queries. At the root of your project, create a Movie.cs file with the following C# code:

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;

[BsonIgnoreExtraElements]
public class Movie {

    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; }

    [BsonElement("title")]
    public string Title { get; set; } = null!;

    [BsonElement("year")]
    public int Year { get; set; }

    [BsonElement("runtime")]
    public int Runtime { get; set; }

    [BsonElement("plot")]
    [BsonIgnoreIfNull]
    public string Plot { get; set; } = null!;

    [BsonElement("cast")]
    [BsonIgnoreIfNull]
    public List<string> Cast { get; set; } = null!;

}

We used a class like the above in our previous tutorials. We’ve just defined a few of our fields, mapped them to BSON fields in our database, and told our class to ignore any extra fields that may exist in our database that we chose not to define in our class.

Let’s say that we want to return movies that were released between 1980 and 1990. If we weren’t using LINQ, we’d be doing something like the following in our Program.cs file:

using MongoDB.Bson;
using MongoDB.Driver;

MongoClient client = new MongoClient(
    Environment.GetEnvironmentVariable("ATLAS_URI")
);

IMongoCollection<Movie> moviesCollection = client.GetDatabase("sample_mflix").GetCollection<Movie>("movies");

BsonDocument filter = new BsonDocument{
    { 
        "year", new BsonDocument{
            { "$gt", 1980 },
            { "$lt", 1990 }
        } 
    }
};

List<Movie> movies = moviesCollection.Find(filter).ToList();

foreach(Movie movie in movies) {
    Console.WriteLine($"{movie.Title}: {movie.Plot}");
}

However, since we want to use LINQ, we can update our Program.cs file to look like the following:

using MongoDB.Driver;
using MongoDB.Driver.Linq;

MongoClientSettings settings = MongoClientSettings.FromConnectionString(
    Environment.GetEnvironmentVariable("ATLAS_URI")
);

settings.LinqProvider = LinqProvider.V3;

MongoClient client = new MongoClient(settings);

IMongoCollection<Movie> moviesCollection = client.GetDatabase("sample_mflix").GetCollection<Movie>("movies");

IMongoQueryable<Movie> results =
            from movie in moviesCollection.AsQueryable()
            where movie.Year > 1980 && movie.Year < 1990
            select movie;

foreach(Movie result in results) {
    Console.WriteLine("{0}: {1}", result.Title, result.Plot);
}

In the above code, we are getting a reference to our collection and creating a LINQ query. To break down the LINQ query to see how it relates to MongoDB, we have the following:

1. The “WHERE” operator is the equivalent to doing a “$MATCH” or a filter within MongoDB. The documents have to match the criteria in this step.
2. The “SELECT” operator is the equivalent to doing a projection or using the “$PROJECT” operator. We’re defining which fields should be returned from the query—in this case, all fields that we’ve defined in our class.

To diversify our example a bit, we’re going to change the match condition to match within an array, something non-flat.

Change the LINQ query to look like the following:

var results =
            from movie in moviesCollection.AsQueryable()
            where movie.Cast.Contains("Michael Keaton")
            select new { movie.Title, movie.Plot };

A few things changed in the above code along with the filter. First, you’ll notice that we are matching on the Cast array as long as “Michael Keaton” exists in that array. Next, you’ll notice that we’re doing a projection to only return the movie title and the movie plot instead of all other fields that might exist in the data.

We’re going to make things slightly more complex now in terms of our query. This time we’re going to do what would have been a MongoDB aggregation pipeline, but this time using LINQ.

Change the C# code in the Program.cs file to look like the following:

using MongoDB.Driver;
using MongoDB.Driver.Linq;

MongoClientSettings settings = MongoClientSettings.FromConnectionString(
    Environment.GetEnvironmentVariable("ATLAS_URI")
);

settings.LinqProvider = LinqProvider.V3;

MongoClient client = new MongoClient(settings);

IMongoCollection<Movie> moviesCollection = client.GetDatabase("sample_mflix").GetCollection<Movie>("movies");

var results = 
            from movie in moviesCollection.AsQueryable()
            where movie.Cast.Contains("Ryan Reynolds")
            from cast in movie.Cast
            where cast == "Ryan Reynolds"
            group movie by cast into g
            select new { Cast = g.Key, Sum = g.Sum(x => x.Runtime) };

foreach(var result in results) {
    Console.WriteLine("{0} appeared on screen for {1} minutes!", result.Cast, result.Sum);
}

In the above LINQ query, we’re doing a series of steps, just like stages in an aggregation pipeline. These stages can be broken down like the following:

1. Match all documents where “Ryan Reynolds” is in the cast.
2. Unwind the array of cast members so the documents sit adjacent to each other. This will flatten the array for us.
3. Do another match on the now smaller subset of documents, filtering out only results that have “Ryan Reynolds” in them.
4. Group the remaining results by the cast, which will only be “Ryan Reynolds” in this example.
5. Project only the group key, which is the cast member, and the sum of all the movie runtimes.

If you haven’t figured it out yet, what we attempted to do was determine the total amount of screen time Ryan Reynolds has had. We isolated our result set to only documents with Ryan Reynolds, and then we summed the runtime of the documents that were matched.

While the full scope of the MongoDB aggregation pipeline isn’t supported with LINQ, you’ll be able to accomplish quite a bit, resulting in a lot cleaner looking code. To get an idea of the supported operators, take a look at the MongoDB LINQ documentation.

Conclusion

You just got a taste of LINQ with MongoDB in your .NET Core applications. While you don’t have to use LINQ, as demonstrated in a few previous tutorials, it’s common practice amongst C# developers.

Got a question about this tutorial? Check out the MongoDB Community Forums for help!

This content first appeared on MongoDB.

Nic Raboy

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in C#, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Unity. Nic writes about his development experiences related to making web and mobile development easier to understand.