Azure Cosmos DB: Connect to a MongoDB app using .NET

Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

This tutorial demonstrates how to create an Azure Cosmos DB account using the Azure portal, and how to create a database and collection to store data using the MongoDB API.

This tutorial covers the following tasks:

  • Create an Azure Cosmos DB account
  • Update your connection string
  • Create a MongoDB app on a virtual machine

Create a database account

Let's start by creating an Azure Cosmos DB account in the Azure portal.

If you don't have an Azure subscription, create a free account before you begin.

Alternatively, you can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Or you can use the Azure Cosmos DB Emulator for this tutorial with a connection string of

mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true

Tip

  1. In a new window, sign in to the Azure portal.
  2. In the left menu, click Create a resource, click Databases, and then under Azure Cosmos DB, click Create.

    Screen shot of the Azure portal, highlighting More Services, and Azure Cosmos DB

  3. In the New account blade, specify MongoDB as the API and fill out your desired configuration for the Azure Cosmos DB account.

    • ID must be a unique name you wish to use to identify your Azure Cosmos DB account. It may only contain lower case letters, numbers, the '-' character, and must be between 3 and 50 characters.
    • Subscription is your Azure subscription. It will be filled out for you.
    • Resource Group is the resource group name for your Azure Cosmos DB account. Select Create New, then enter a new resource-group name for your account. For simplicity, you can use the same name as your ID.
    • Location is the geographic location where your Azure Cosmos DB instance is located. Choose the location closest to your users.

      Then click Create.

      The new account page for Azure Cosmos DB

  4. The account creation takes a few minutes. Wait for the portal to display the Congratulations! Your Azure Cosmos DB account with MongoDB API is ready page.

    The Azure portal Notifications pane

Update your connection string

  1. In the Azure portal, in the Azure Cosmos DB page, select the API for MongoDB account.
  2. In the left bar of the account blade, click Quick start.
  3. Choose your platform (.NET driver, Node.js driver, MongoDB Shell, Java driver, Python driver). If you don't see your driver or tool listed, don't worry, we continuously document more connection code snippets.
  4. Copy and paste the code snippet into your MongoDB app, and you are ready to go.

Set up your MongoDB app

You can use the Create a web app in Azure that connects to MongoDB running on a virtual machine tutorial, with minimal modification, to quickly setup a MongoDB application (either locally or published to an Azure web app) that connects to an API for MongoDB account.

  1. Follow the tutorial, with one modification. Replace the Dal.cs code with this:

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Web;
    using MyTaskListApp.Models;
    using MongoDB.Driver;
    using MongoDB.Bson;
    using System.Configuration;
    using System.Security.Authentication;
    
    namespace MyTaskListApp
    {
        public class Dal : IDisposable
        {
            //private MongoServer mongoServer = null;
            private bool disposed = false;
    
            // To do: update the connection string with the DNS name
            // or IP address of your server. 
            //For example, "mongodb://testlinux.cloudapp.net
            private string connectionString = "mongodb://localhost:27017";
            private string userName = "<your user name>";
            private string host = "<your host>";
            private string password = "<your password>";
    
            // This sample uses a database named "Tasks" and a 
            //collection named "TasksList".  The database and collection 
            //will be automatically created if they don't already exist.
            private string dbName = "Tasks";
            private string collectionName = "TasksList";
    
            // Default constructor.        
            public Dal()
            {
            }
    
            // Gets all Task items from the MongoDB server.        
            public List<MyTask> GetAllTasks()
            {
                try
                {
                    var collection = GetTasksCollection();
                    return collection.Find(new BsonDocument()).ToList();
                }
                catch (MongoConnectionException)
                {
                    return new List<MyTask>();
                }
            }
    
            // Creates a Task and inserts it into the collection in MongoDB.
            public void CreateTask(MyTask task)
            {
                var collection = GetTasksCollectionForEdit();
                try
                {
                    collection.InsertOne(task);
                }
                catch (MongoCommandException ex)
                {
                    string msg = ex.Message;
                }
            }
    
            private IMongoCollection<MyTask> GetTasksCollection()
            {
                MongoClientSettings settings = new MongoClientSettings();
                settings.Server = new MongoServerAddress(host, 10255);
                settings.UseSsl = true;
                settings.SslSettings = new SslSettings();
                settings.SslSettings.EnabledSslProtocols = SslProtocols.Tls12;
    
                MongoIdentity identity = new MongoInternalIdentity(dbName, userName);
                MongoIdentityEvidence evidence = new PasswordEvidence(password);
    
                settings.Credentials = new List<MongoCredential>()
                {
                    new MongoCredential("SCRAM-SHA-1", identity, evidence)
                };
    
                MongoClient client = new MongoClient(settings);
                var database = client.GetDatabase(dbName);
                var todoTaskCollection = database.GetCollection<MyTask>(collectionName);
                return todoTaskCollection;
            }
    
            private IMongoCollection<MyTask> GetTasksCollectionForEdit()
            {
                MongoClientSettings settings = new MongoClientSettings();
                settings.Server = new MongoServerAddress(host, 10255);
                settings.UseSsl = true;
                settings.SslSettings = new SslSettings();
                settings.SslSettings.EnabledSslProtocols = SslProtocols.Tls12;
    
                MongoIdentity identity = new MongoInternalIdentity(dbName, userName);
                MongoIdentityEvidence evidence = new PasswordEvidence(password);
    
                settings.Credentials = new List<MongoCredential>()
                {
                    new MongoCredential("SCRAM-SHA-1", identity, evidence)
                };
                MongoClient client = new MongoClient(settings);
                var database = client.GetDatabase(dbName);
                var todoTaskCollection = database.GetCollection<MyTask>(collectionName);
                return todoTaskCollection;
            }
    
            # region IDisposable
    
            public void Dispose()
            {
                this.Dispose(true);
                GC.SuppressFinalize(this);
            }
    
            protected virtual void Dispose(bool disposing)
            {
                if (!this.disposed)
                {
                    if (disposing)
                    {
                    }
                }
    
                this.disposed = true;
            }
    
            # endregion
        }
    }
    
  2. Modify the following variables in the Dal.cs file per your account settings from the Keys page in the Azure portal:

    private string userName = "<your user name>";
    private string host = "<your host>";
    private string password = "<your password>";
    
  3. Use the app!

Clean up resources

If you're not going to continue to use this app, use the following steps to delete all resources created by this tutorial in the Azure portal.

  1. From the left-hand menu in the Azure portal, click Resource groups and then click the name of the resource you created.
  2. On your resource group page, click Delete, type the name of the resource to delete in the text box, and then click Delete.

Next steps

In this tutorial, you've done the following:

  • Create an Azure Cosmos DB account
  • Update your connection string
  • Create a MongoDB app on a virtual machine

You can proceed to the next tutorial and import your MongoDB data to Azure Cosmos DB.