One of the most important decisions that you’ll make when designing an app is what type of database to use.

Not too long ago, the choice was limited to relational databases like SQL server. However, now NoSQL databases are on the scene with the benefits of allowing applications to handle large amounts of structured and unstructured data at the same time, the ability to easily model data as objects, and massively scale across servers.

MongoDB is a NoSQL database that stores documents in a binary JSON format that has been popular in the Node.js community for a while. Azure Cosmos DB is a fully managed cloud database. With just a few clicks you can configure a database that is 100% compatible with the MongoDB API. 

Despite the popularity of MongoDB for Node.js solution, a fully supported and maintained driver for .NET exists. The driver is implemented in .NET Standard which means it is compatible with multiple platforms, including Xamarin. 

This article will show you how to create your first Xamarin app using MongoDB! We’ll query data using LINQ, insert, and delete data. By the end of this article you’ll have the info you need to create MongoDB powered Xamarin apps yourself.

You can find all of the code for a demo app in this GitHub repo.

Set Up the Environment

For the purposes of this tutorial, our MongoDB will be hosted in Azure Cosmos DB.

First, to get your instance of Azure Cosmos DB set up and ready to use, follow the instructions on the Azure Cosmos DB documentation page. Create a free Azure account using this link if you don’t already have one set up.

The MongoDB.NET library enables the communication between Xamarin apps and the MongoDB. Search for MongoDB.Driver using the NuGet Package Manager in Visual Studio or Visual Studio for Mac and dd that library to all of your projects.

Connect to MongoDB

Next, our app needs to connect to the MongoDB. Use the MongoClient object to obtain a reference to the IMongoDatabase . Then use the IMongoDatabase object to obtain a reference to the IMongoCollection<T> class. (See the demo project for an example of this connection code.)

To understand the connection process, it helps to understand how MongoDB arranges its data.

The Azure Cosmos DB account created above is the first level of organization. One or more databases sit under the account. Then one or more collections comprise a database. The last level, documents, reside within a collection.

To read and write documents, our app will use the IMongoCollection<T> class. Where the generic is our model, or a strongly typed representation of the document.

Query Data

We use IMongoCollection<T> to query the documents in the collection. In mobile applications it is important to query asynchronously to avoid blocking the UI thread and provide a better user experience. A great feature of .NET is LINQ queries. LINQ helps developers write complex query statements in an easy to understand syntax, fortunately the MongoDB driver as full support for LINQ queries.

The code to return every document in a collection looks like the following:

public async Task<List<ToDoItem>> GetAllItems()
{
    var allItems = await ToDoItemsCollection
        .Find(new BsonDocument())
        .ToListAsync();

    return allItems;
}

One thing to note from above is the BsonDocument in the  Find function. That indicates an empty filter, and is needed to return any documents.

If the collection contains thousands of documents, or we want to filter documents, we should use a different query.

This query filters on name and also only returns the first 10 records.

public async Task<List<ToDoItem>> SearchByName(string name)
{
    var results = await ToDoItemsCollection
                    .AsQueryable()
                    .Where(tdi => tdi.Name.Contains(name))
                    .Take(10)
                    .ToListAsync();

    return results;
}

The AsQueryable() extension provides an interface that supports LINQ extensions and makes it possible to leverage filters, skip and take statements, etc.

Write Data

The MongoDB .NET library also provides a simple asynchronous data modification API.

Inserting data looks like this:

public async Task InsertItem(ToDoItem item)
{
    await ToDoItemsCollection.InsertOneAsync(item);
}

To replace the entire document with a single update use the following code:

public async Task UpdateItem(ToDoItem item)
{
    await ToDoItemsCollection.ReplaceOneAsync(tdi => tdi.Id == item.Id, item);
}

The MongoDB driver defines attributes to provide additional information when they are used to decorate classes and properties. For example, the  [BsonId]  attribute specifies which property on the class should be used as the unique key or identifier for tat instance/document.

Summing Up

MongoDB is a well known and widely used document database. The combination of Azure Cosmos DB and the .NET MongoDB driver makes it a viable solutions for Xamarin apps that should ideally feel familiar to .NET mobile developers.

To learn more about MongoDB, see the documentation here. Read more about Cosmos DB with MongoDB here. Give the demo app a test drive here!

And, as always, please feel free to discuss this post in the forums!