Why Azure Cosmos DB?
Azure Cosmos DB is the recommended backend database for Xamarin mobile apps due to its speed, scalability and many other cool features such as geospatial support. For a mobile developer like me, Azure Cosmos DB is appealing as there is no middle-tier i.e no Api work is required as that is all handled in the Azure Cosmos DB architecture.
Beginners guide to Azure Cosmos DB
Integrating Azure Cosmos DB to Xamarin app solution is simple. All we need it two things:
- Create the Azure Cosmos DB in azure portal
- Integrate it within out Xamarin app
Creating Azure Cosmos DB
There are two ways to start creating Azure Cosmos DB in cloud. We could mock the Azure Cosmos DB locally using the Azure Cosmos Emulator. This is quite a nifty tool as we do not need to worry about creating azure portal accounts or any paid subscriptions. Fortunately, at the time of writing this, azure provided a free tier which gets you the first 400 RU/s and 5 GB of storage for free in an account. Learn more about free tier.
To begin with, you will need an azure subscription. You can create a free azure portal account if you don’t have one. Thereafter, follow the below summaried steps or for more detailed instructions, check out Azure Cosmos DB quick start
- Login to azure portal
- Click on create resource
- Search for Azure Cosmos DB
- Create Azure Cosmos DB account
- Review and create
- Wait for deployment to complete
Add a container
Containers are more like tables in a normal SQL server database with the key difference begin, they do not conform to a strict schema structure. Follow these steps to create a container:
- Select the newly created resource
- Go to Data explorer in the left panel
- Click New container
- Enter your database name
- Enter container name
- Enter Partitioning key
Obtaining API Keys
To access the Azure Cosmos DB from our Xamarin app, we need the URL and the primary key values from the portal which can be retrieved from:
- Select Keys from the left panel
- Select Read-write keys
- Copy URL value
- Copy Primary key value
Initially, we will hard code these values in the Xamarin app as explained below. Once we are happy with the basic database setup we will dive into authenticating users to securely obtain these values.
Integrating Azure Cosmos DB to our Xamarin app
- Install Microsoft.Azure.DocumentDb.Core Nuget package to the Xamarin app solution.
- Create an AzureCosmosDB class in a services folder and enter the database name, collection name, API URL and primary Keys values as described in the previous steps. These values are needed to initialize the document client which is used to configure and execute requests against the Azure Cosmos DB account
Create the CRUD operations methods as shown below
Partition Key value must be supplied for this operation – When you encounter this error during a delete operation, ensure you have both the item primary Id and the partition key value included the the query. The Partition Key can be included through the RequestOptions parameter as shown below:
And that’s it! You can now use these CRUD operations to add, edit and delete items to your Azure Cosmos DB. To view the data in cloud:
- Login to the azure portal,
- Select the azure cosmos db resource
- Go to Data Explorer
- Click Edit Filter
- Enter a custom SQL query or Click Apply filter.