Tutorial: Build mobile applications with Xamarin and Azure Cosmos DB


Most mobile apps need to store data in the cloud, and Azure Cosmos DB is a cloud database for mobile apps. It has everything a mobile developer need. It is a fully managed database as a service that scales on demand. It can bring your data to your application transparently, wherever your users are located around the globe. By using the Azure Cosmos DB .NET Core SDK, you can enable Xamarin mobile apps to interact directly with Azure Cosmos DB, without a middle tier.

This article provides a tutorial for building mobile apps with Xamarin and Azure Cosmos DB. You can find the complete source code for the tutorial at Xamarin and Azure Cosmos DB on GitHub, including how to manage users and permissions.

Azure Cosmos DB capabilities for mobile apps

Azure Cosmos DB provides the following key capabilities for mobile app developers:

Azure Cosmos DB capabilities for mobile apps

  • Rich queries over schemaless data. Azure Cosmos DB stores data as schemaless JSON documents in heterogeneous collections. It offers rich and fast queries without the need to worry about schemas or indexes.
  • Fast throughput. It takes only a few milliseconds to read and write documents with Azure Cosmos DB. Developers can specify the throughput they need, and Azure Cosmos DB honors it with 99.99% availability SLA for all single region accounts and all multi-region accounts with relaxed consistency, and 99.999% read availability on all multi-region database accounts.
  • Limitless scale. Your Azure Cosmos containers grow as your app grows. You can start with small data size and throughput of hundreds of requests per second. Your collections or databases can grow to petabytes of data and arbitrarily large throughput with hundreds of millions of requests per second.
  • Globally distributed. Mobile app users are on the go, often across the world. Azure Cosmos DB is a globally distributed database. Click the map to make your data accessible to your users.
  • Built-in rich authorization. With Azure Cosmos DB, you can easily implement popular patterns like per-user data or multiuser shared data, without complex custom authorization code.
  • Geospatial queries. Many mobile apps offer geo-contextual experiences today. With first-class support for geospatial types, Azure Cosmos DB makes creating these experiences easy to accomplish.
  • Binary attachments. Your app data often includes binary blobs. Native support for attachments makes it easier to use Azure Cosmos DB as a one-stop shop for your app data.

Azure Cosmos DB and Xamarin tutorial

The following tutorial shows how to build a mobile application by using Xamarin and Azure Cosmos DB. You can find the complete source code for the tutorial at Xamarin and Azure Cosmos DB on GitHub.

Get started

It's easy to get started with Azure Cosmos DB. Go to the Azure portal, and create a new Azure Cosmos DB account. Click the Quick start tab. Download the Xamarin Forms to-do list sample that is already connected to your Azure Cosmos DB account.

Azure Cosmos DB Quick start for mobile apps

Or if you have an existing Xamarin app, you can add the Azure Cosmos DB NuGet package. Azure Cosmos DB supports Xamarin.iOS, Xamarin.Android, and Xamarin Forms shared libraries.

Work with data

Your data records are stored in Azure Cosmos DB as schemaless JSON documents in heterogeneous collections. You can store documents with different structures in the same collection:

    var result = await client.CreateDocumentAsync(collectionLink, todoItem);

In your Xamarin projects, you can use language-integrated queries over schemaless data:

    var query = await client.CreateDocumentQuery<ToDoItem>(collectionLink)
                    .Where(todoItem => todoItem.Complete == false)

    Items = new List<TodoItem>();
    while (query.HasMoreResults) {
        Items.AddRange(await query.ExecuteNextAsync<TodoItem>());

Add users

Like many get started samples, the Azure Cosmos DB sample you downloaded authenticates to the service by using a primary key hardcoded in the app's code. This default is not a good practice for an app you intend to run anywhere except on your local emulator. If an unauthorized user obtained the primary key, all the data across your Azure Cosmos DB account could be compromised. Instead, you want your app to access only the records for the signed-in user. Azure Cosmos DB allows developers to grant application read or read/write permission to a collection, a set of documents grouped by a partition key, or a specific document.

Follow these steps to modify the to-do list app to a multiuser to-do list app:

  1. Add Login to your app by using Facebook, Active Directory, or any other provider.

  2. Create an Azure Cosmos DB UserItems collection with /userId as the partition key. Specifying the partition key for your collection allows Azure Cosmos DB to scale infinitely as the number of your app users grows, while continuing to offer fast queries.

  3. Add Azure Cosmos DB Resource Token Broker. This simple Web API authenticates users and issues short-lived tokens to signed-in users with access only to the documents within their partition. In this example, Resource Token Broker is hosted in App Service.

  4. Modify the app to authenticate to Resource Token Broker with Facebook, and request the resource tokens for the signed-in Facebook users. You can then access their data in the UserItems collection.

You can find a complete code sample of this pattern at Resource Token Broker on GitHub. This diagram illustrates the solution:

Azure Cosmos DB users and permissions broker

If you want two users to have, access to the same to-do list, you can add additional permissions to the access token in Resource Token Broker.

Scale on demand

Azure Cosmos DB is a managed database as a service. As your user base grows, you don't need to worry about provisioning VMs or increasing cores. All you need to tell Azure Cosmos DB is how many operations per second (throughput) your app needs. You can specify the throughput via the Scale tab by using a measure of throughput called Request Units (RUs) per second. For example, a read operation on a 1-KB document requires one RU. You can also add alerts to the Throughput metric to monitor the traffic growth and programmatically change the throughput as alerts fire.

Azure Cosmos DB scale throughput on demand

Go planet scale

As your app gains popularity, you might gain users across the globe. Or maybe you want to be prepared for unforeseen events. Go to the Azure portal, and open your Azure Cosmos DB account. Click the map to make your data continuously replicate to any number of regions across the world. This capability makes your data available wherever your users are. You can also add failover policies to be prepared for contingencies.

Azure Cosmos DB scale across geographic regions

Congratulations. You have completed the solution and have a mobile app with Xamarin and Azure Cosmos DB. Follow similar steps to build Cordova apps by using the Azure Cosmos DB JavaScript SDK and native iOS/Android apps by using Azure Cosmos DB REST APIs.

Next steps