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.

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

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

  3. In the New account blade, specify the desired configuration for the Azure Cosmos DB account.

    With Azure Cosmos DB, you can choose one of four programming models: Gremlin (graph), MongoDB, SQL (DocumentDB), and Table (key-value).

    In this quick start we'll be programming against the MongoDB API so you'll choose MongoDB as you fill out the form. But if you have graph data for a social media app, document data from a catalog app, or key/value (table) data, realize that Azure Cosmos DB can provide a highly available, globally-distributed database service platform for all your mission-critical applications.

    Fill out the New account blade using the information in the table as a guide.

    Screen shot of the New Azure Cosmos DB blade

    Setting Suggested value Description
    ID Unique value A unique name you choose to identify the Azure Cosmos DB account. documents.azure.com is appended to the ID you provide to create your URI, so use a unique but identifiable ID. The ID may contain only lowercase letters, numbers, and the '-' character, and must be between 3 and 50 characters.
    API MongoDB We'll be programming against the MongoDB API later in this article.
    Subscription Your subscription The Azure subscription that you want to use for the Azure Cosmos DB account.
    Resource Group The same value as ID The new resource group name for your account. For simplicity, you can use the same name as your ID.
    Location The region closest to your users The geographic location in which to host your Azure Cosmos DB account. Choose the location closest to your users to give them the fastest access to the data.
  4. Click Create to create the account.

  5. On the toolbar, click Notifications to monitor the deployment process.

    Deployment started notification

  6. When the deployment is complete, open the new account from the All Resources tile.

    DocumentDB account on the All Resources tile

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.