Getting started with Azure DocumentDB

I don’t have this entirely worked-out, but I wanted to jot some of this down, to at least get started. As you may know, there has been a new trend of “NoSQL” databases lately. These are database management systems which can store “documents”, or semi-ordered chunks of data. If you are familiar with a relational database management system (RDBMS), that technology revolves around the database. The database is in charge of the structure, data integrity, and referential integrity. The database IS the “application”,  and the UI is simply an interface to get to the application.

NoSQL databases are very pliable. The responsibility for making sense of the data is left to the application, in code. If you follow the Bob Martin style of coding, you know this is a good thing. Your “application” should exist as code, where it can be tested, and properly-managed. The database should, ideally, be a superfluous add-on which lives to serve the needs of the “application”. With NoSQL, the responsibility shifts from being database-centric, to code-centric. There are also other benefits of NoSQL too – like tremendous performance and internet-scalability.

Although I’ve yet to bring an app to production using it, I had a lot of fun exploring MongoDB – which is arguably the most popular implementation. DocumentDB is very similar, in concept.

What is DocumentDB?
DocumentDB is a NoSQL implementation produced by Microsoft. It is a Platform as a Service (PaaS) offering which is only available via Azure. Technically, it’s an HTTPS endpoint in front of the database. So, from your application, you could use API’s, which use the secure RESTful endpoints, to get and put your data.

Where do I begin?
I’ll assume you have a Microsoft Azure account? If not, and if you have MSDN – then you just need to enable it. If you don’t have MSDN, even through your work – then consider pursuing BizSpark. This is a free offering from Microsoft that allows independent software vendors (like you) to get MSDN and up to $150/month in Azure credit. So now… I’ll assume you have a Microsoft Azure Account?

You MUST do this next part through the “new” Azure portal. “But the new portal is really horrible, why are you making me use it?” you’ll ask. I know, I don’t like the new portal either, but that is the only place where this feature is!

In the new Azure portal, click the “+” in the bottom-left and choose “DocumentDB” from the menu, and follow the prompts:



Connecting to it from Visual Studio:
Now you have an empty DocumentDB service which is ready for some “databases” and “collections”. Databases are containers, and collections are document collections. They are similar to tables in an RDBMS, but collection documents don’t need to have the same structure.

As discussed, the DocumentDB service is really an HTTPS endpoint. So, to easily interact with it – use the SDK. Specifically, install the NuGet package into your project. When you click on the properties of your newly-created DocumentDB in the portal, you’ll see some options. Click on “Install .NET SDK”:


That sends you to this NuGet package:

Which means you can either install it from the Package Manager Console like this:

Install-Package Microsoft.Azure.Documents.Client –Pre

and you’ll see this:


or via the “Manage NuGet Packages” for the project, like this:


Writing some code:
OK, I started from the readily-accessible samples located here:

These are quite excellent. However, when I tried to get this going with mine, I ran into some trouble. One frustrating thing is that this NuGet package is pre-release so there is no Intellisense with the API. Using that sample code, I could create a database, a collection, and then insert a new document into the collection (like, saving a “Customer” record for example) – but when I used their example for querying, it simply doesn’t match. I have a simple .Where(..) clause that matches on a Guid and it just will not match to the id in the database.

So, that’s where I stopped. Here’s a quick look at how the conventions look for this type of database:


and that all operates on the context of this “client”, which is in the outer scope:


Bottom line:
This seems to be pretty similar to MongoDB, CouchDB, and others. The API here is a little rough. There is no Intellisence, and I got several unhandled NullReferenceException’s which are occurring inside of the component. That’s not good. In their defense though, this is pre-release software.

As far as using this in a project, I really just have one concern. That is, this always has to live in Azure. Your dev, qa, and production would all have to be hosted in Azure – costing you money, every second of the day – whether you are using it or not. This is a far cry from something like MongoDB which is free, open source, and runs on practically anything.

So for me, this has the same short-comings as the rest of Azure – you NEED the cloud infrastructure, and it costs you money every second of the day. If they had an offline version that you could host at your company, then it would be a complete no-brainer to host dev and qa locally, and migrate to Azure for production. It would be ideal to have the same infrastructure software everywhere.

Anyhow – hopefully this helps a little, or at least gets you basically familiar with what DocumentDB is and what it can do.

Posted in Development Tools, General, MongoDB, New Technology, NoSQL, Uncategorized
2 comments on “Getting started with Azure DocumentDB
  1. Emmad says:

    Thanks for the article.
    The following page referenced in the article does not exist.


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 )

Google+ photo

You are commenting using your Google+ 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.


Enter your email address to follow this blog and receive notifications of new posts by email.

Join 9 other followers

%d bloggers like this: