How do you set up the Azure CosmosDb Emulator

For many of us starting off new to CosmosDb, the cost of provisioning a CosmosDb to learn with is probably a bit high. In this blog, we’ll go through how to install the emulator to let you do this locally – for free.

Download and Install

So first off, head to the Microsoft Download Center and get yourself a copy of the executable. It’s lightweight at 48mb and contains a huge amount of content as it replicates the functionality of a real CosmosDb instance almost exactly, giving you a highly realistic local environment to develop in.

Accept the terms and conditions, click install, allow the security prompt that comes up and wait for about 30 seconds. Voila! Make sure the tick box for ‘Launch Azure CosmosDb Emulator’ is ticked and then Finish to start it up. There might be a few services that get picked up by your firewall initially, but just allow access to them as we know its a safe install.

Note: Windows will start the emulator for you, but depending on how your pc or laptop is set up, you might encounter a warning saying that port:8081 is in use.

Azure CosmosDb Emulator 3

Microsoft has provided some guidance in the message but if you’ve not used the command line interface before it can be a bit confusing.  The example below might change depending on your installed location, but it is where it was for me by default.

cd C:\Program Files\Azure Cosmos DB Emulator

CosmosDb.Emulator.exe /Port=12345

This should update the port to 12345 (or whatever you decide is open on your system) and let it initialise correctly.

Working with the emulator

You will find the emulator in the system tray in the bottom right of your screen (next to the clock). It gives you a few options if you right click on it but the one we’re interested in is the ‘Open Data Explorer’ one.

Azure CosmosDb Emulator 1

The Data Explorer (which is different from the Azure Storage Explorer) is a browser-based tool that lets you interact with your local cosmosdb instance in pretty much the same way as the real thing.

It opens on a page confirming that your emulator is running as well as providing you with the information you’ll need to connect to it. If you’re planning on following along with the demos for working with CosmosDb in the console, we would use the URI and Primary Key, but if you’re a bit more experienced and want to get stuck in with say, MongoDB, the connection string is helpfully provided here as well.

Azure CosmosDb Emulator 2

There’s also a series of links below it that have helpful things like a sample .net app so if you just want a working premade project to get started in, that’s here too.

If you just want to inspect the data that you’ve saved you can select the ‘Explorer’ value in the sidebar menu.

Azure CosmosDb Emulator 4

The explorer is a great tool to inspect and interact with your databases. You can create databases, collections and documents to your heart’s content and then use a basic query filter to retrieve them again. It’s worth noting that the default is a single partitioned db, or 25 fixed but that can be changed on the command line.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.