• Platforms >
  • Build an Application to Connect to MongoDB on Azure

Build an Application to Connect to MongoDB on Azure

This page outlines the steps necessary to set up your application to connect to the MongoDB cluster running on Azure worker roles. It is not a tutorial on building an application.

When connecting to a MongoDB replica set, the client application (driver) needs to be able to connect individually to each of the members of the replica set to route reads and writes appropriately. Also with the MongoDB worker role being deployed with internal endpoints (only accessible from within the same service), the client application needs to be deployed as part of the same cloud service as the MongoDB application.

MongoDB.WindowsAzure.Sample.MvcMovie is an example client application that follows the steps described below. This sample application along with its deployment cloud project can be found in the MongoDB on Azure Github repos.

Connect to MongoDB

Use the ConnectionUtilities class included as part of the MongoDB.WindowsAzure.Common project. To connect to the MongoDB replica set deployed as part of you cloud service, you need to:

Use the MongoDB.WindowsAzure.Common project

using MongoDB.WindowsAzure.Common;

Use the following code snippet to obtain a replica set connection to the database

MongoServerSettingsserverSettings = ConnectionUtilities.GetConnectionSettings();
MongoServer server = MongoServer.Create(settings);
MongoDatabase database = server["mydb"];

To create a connection that allows reading from secondaries use:

MongoServerSettingsserverSettings = ConnectionUtilities.GetConnectionSettings();
settings.SlaveOk = true;
MongoServer server = MongoServer.Create(settings);
MongoDatabase database = server["mydb"];

For more information on the MongoDB .Net Driver’s ConnectionSettings object, see the API docs.


To account for possible changes in the IPs of the instances running MongoDB, the worker role uses the hosts file to alias each of the instances. Hence the client application instance needs the same instances. Additionally the client application must also have the name of the replica set.

Specify Replica Set Name

Ensure your client application deployment project has a setting called ReplicaSetName that is set to the same value as the ReplicaSetName setting of the MongoDB.WindowsAzure.MongoDB role. This can be verified by ensuring your ServiceDefinition.csdef file has the following setting as part of your client application role:

   <Setting name="ReplicaSetName" />

Also your ServiceConfiguration.*.cscfg files have the value set:

<Role name="MongoDB.WindowsAzure.Sample.MvcMovie">
   <Instances count="1" />
      <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="UseDevelopmentStorage=true" />
      <Setting name="ReplicaSetName" value="rs" />

Set Up Host Aliases

The included MongoDB.WindowsAzure.InstanceMaintainer utility takes care of correctly creating the hosts file. Include this as part of your client application project and ensure it is always deployed to the Azure role instance. For example, in the sample MongoDB.WindowsAzure.Sample.MvcMovie application the following is specified in the csproj:

<None Include="..\..\..\MongoDB.WindowsAzure.InstanceMaintainer\$(InstanceMaintainerPath)\MongoDB.WindowsAzure.InstanceMaintainer.exe.config">

Ensure the Instance Maintainer is Started

The InstanceMaintainer utility must always be running on your client application role to ensure it maintains the hosts file. To enable that, it needs to be started as part of your role startup. This is done through the Startup setting on your csdef file. For example, in the included MvcMovie sample app, this is specified as:

<WebRole name="MongoDB.WindowsAzure.Sample.MvcMovie" vmsize="Small">
      <Task commandLine="InstanceMaintainer.cmd" executionContext="elevated" taskType="background" />