Close this search box.

Exploring Microsoft Azure DocumentDB

In this blog post, I will provide an introduction to DocumentDB by showing you how to create a collection (a collection is a container that stores your data), and how to connect to your collection to add and fetch data. DocumentDB is a newer no-sql data storage engine that is hosted in the Microsoft Azure cloud exclusively. Because DocumentDB stores records as JSON objects, it is a natural database engine for developers. Unlike other offerings however, it also offers key features such as automatic indexing, server-side triggers, functions and stored procedures (through Javascript).

Creating a DocumentDB Database

First, let’s create a new DocumentDB database so we can start exploring this service; three things need to be created:  an account, a database, and a collection (where data is actually stored). An account can host multiple databases, and each database can host multiple collections. From you Azure portal ( find DocumentDB from the list of available services, and create a new DocumentDB account. The Resource Group is a logical container allowing to group, view, and manage related services. The screenshot below shows the information I have provided.

Once the account has been created, the screen changes to show you a menu of options from which you can create databases; of importance, DocumentDB allows you to change the default consistency of your no-sql databases (no-sql database consistency is an important concept as it can impact performance, availability and consistency – see Consistency levels in DocumentDB); we will keep the default setting. Also note an important configuration property: your keys. Locate the Keys configuration menu to reveal your access keys. Note that DocumentDB allows you to manage read-only keys as well.

Select Overview from the top of this menu, and click on Add Database and enter a database identifier (which is the database name; my database is called ‘testdb’), and click OK.

Once the database has been created, you will need to create a collection. Select the database to open up a new panel, and click on Add Collection. Enter the necessary information and click OK (see the information I provided below; my collection name is logdata; I also changed the Throughput to 400 to reduce the cost since this is a test collection).  At this point, we are ready to access this collection and start adding records (in proper no-sql speak, we will be adding documents).

Before jumping into the code, let’s make note of the following information since this will be needed later to connect to DocumentDB.

Database IDtestdbThe database “Id” is the name of the database we created
Collection IdlogdataThe collection “Id” is the name of the collection we created
Endpoint is the URI of your DocumentDB service; use your account name
Auth Key{Look under Keys in your DocumentDB database}This is the Primary Key or Secondary Key of your DocumentDB account

Create a VS2015 Project

Let’s create a simple project using Visual Studio 2015 to access the DocumentDB collection. Note that the complete project and source code can be found here: 

We will create a Console Application to perform a few simple operations. Once you have created the project, you will need to add the DocumentDB SDK.  To install the SDK, find the Microsoft Azure DocumentDB package, or use the following command in the Package Manager Console (if you download the sample code, the package will automatically be downloaded when you first compile):

Install-Package Microsoft.Azure.DocumentDB

Let’s create a class that holds a single log entry in our DocumentDB collection. The class name is LogEntry. We need to have a unique identifier for every document, and it must be called Id.

public class LogEntry {
  public string Id { get; set; }  // Guid of log
  public DateTime DateAdded { get; set; }
  public string Message { get; set; }
  public string Category { get; set; }  // Info, Warning, Error
  public int Severity { get; set; }     // Low, Medium, High
  public string Source { get; set; }    // Application name

Then, we will create a simple Console application that does two things: it can add a new document in our collection, and it can list all the documents from the collection.  The following is the complete code for the console application; note the private variables on top that represent the configuration settings identified previously.

using Microsoft.Azure.Documents;
using Microsoft.Azure.Documents.Client;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DocumentDBLogData {
  class Program {
    static string endpoint =
    static string authKey = "YOUR-PRIMARY-OR-SECONDARY-KEY";
    static string databaseId = "testdb";
    static string collectionId = "logdata";

    static void Main(string[] args) {
      Console.WriteLine("STARTING DocumentDB Demo... ");

      while (true) {
        Console.WriteLine("1: Create new message");
        Console.WriteLine("2: List all messages");

        switch (Console.ReadKey().KeyChar) {
          case '1':

            Console.WriteLine("Adding a record to DocumentDB...");


                "New record added in DocumentDB. Press ENTER to continue.");

          case '2':

            Console.WriteLine("Fetching DocumentDB records...");


            Console.WriteLine("Press ENTER to continue.");


    static void AddLogInfoEntry() {
      using (DocumentClient client =
                 new DocumentClient(new Uri(endpoint), authKey)) {
        var collection =
            UriFactory.CreateDocumentCollectionUri(databaseId, collectionId);
        LogEntry le =
            new LogEntry() { Id = Guid.NewGuid().ToString(),
                             Category = "Info",
                             DateAdded = DateTime.UtcNow,
                             Message = "General message from Console App",
                             Severity = 1,
                             Source = "CONSOLE APP" };

        Document newDoc =
            client.CreateDocumentAsync(collection, le).GetAwaiter().GetResult();

    static void DisplayLogInfoEntry() {
      using (DocumentClient client =
                 new DocumentClient(new Uri(endpoint), authKey)) {
        var collection =
            UriFactory.CreateDocumentCollectionUri(databaseId, collectionId);

        var docs =

        foreach (var doc in docs) {
          string output = "{0}\t{1}\t{2}\t{3}\t{4}";
          output = string.Format(output, doc.Id, doc.DateAdded, doc.Source,
                                 doc.Severity, doc.Message);


By pressing 1, the console application connects to DocumentDB and adds a record to the LogData collection.  By pressing 2, the console application fetches all available documents and displays them on the screen. Note that if you have a large number of records, you will need to add logic to page the operation (let’s say 100 documents at a time for example), and handle retry logic operations if the service is too busy.


This simple introduction to DocumentDB provides a quick overview of the simplicity of this service, along with a sample project for creating and accessing documents. Although DocumentDB is very easy to configure and use in code, many advanced features (not covered in this introduction) are available around performance, security and availability. For a deeper understanding of DocumentDB, please refer to the online MSDN documentation, and the QuickStart provided in the DocumentDB menu inside the Azure Portal.

About Herve Roggero

Herve Roggero, Microsoft Azure MVP, @hroggero, is the founder of Enzo Unified ( Herve’s experience includes software development, architecture, database administration and senior management with both global corporations and startup companies. Herve holds multiple certifications, including an MCDBA, MCSE, MCSD. He also holds a Master’s degree in Business Administration from Indiana University. Herve is the co-author of “PRO SQL Azure” and “PRO SQL Server 2012 Practices” from Apress, a PluralSight author, and runs the Azure Florida Association.v

This article is part of the GWB Archives. Original Author: Herve Roggero

Related Posts