Setting Up Microsoft Azure DocumentDB

DocumentDB is the latest storage option added to Microsoft Azure. It is a NoSQL storage service that stores JSON documents natively and provides indexing capabilities along with other interesting features. This article shall introduce you to this new service.

Setting up a Microsoft Azure DocumentDB

Go to the new Microsoft Azure Portal. https://portal.azure.com/

Click on New, then Data + Storage, click DocumentDB



Enter a Database ID and hit Create.

Please wait while the database is being created.



After the database is created, KEYS button to get the Database URI and its required keys.



We may now start building our App.

Using Microsoft Azure DocumentDB in your Application

Create a new project and add the nuget package Microsoft Azure DocumentDB Client Library.

Go to Tools, then Library Package Manager and click Package Manager Console.

Key in Install-Package Microsoft.Azure.Documents.Client -Pre and hit enter.



Define the Model

In this example, we shall define a class Team, each having an array of players.

public class Team
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }
    public string TeamName { get; set; }
    public Player[] Players { get; set; }
}
public class Player
{
    public string PlayerName { get; set; }
    public int PlayerAge { get; set; }
}

Add the endpoint url and the authorization key.

These values are the same values identified above.

private static string endpointUrl = "";
private static string authorizationKey = "";

Create a new instance of the DocumentClient

The DocumentClient class provides a client-side logical representation of the Azure DocumentDB service. It is used to configure and execute requests against the service.

client = new DocumentClient(new Uri(endpointUrl), authorizationKey);

Create Database

This will return an instance of a database, first creating it if it doesn't already exist.

public async Task<Database> CreateOrGet(string DatabaseID)
{

    var Databases = client.CreateDatabaseQuery().Where(db => db.Id == DatabaseID).ToArray();

    if (Databases.Any())
        return Databases.First();

    return await client.CreateDatabaseAsync(new Database { Id = DatabaseID });
}

Create a document collection

This method returns a document collection, creating it if it doesn't already exist. A document collection is a named logical container for documents.

The method CreateDocumentCollectionQuery creates and returns a query for document collections.

public async Task<DocumentCollection> CreateOrGetCollection(string CollectionID)
{
    var collections = client.CreateDocumentCollectionQuery(database.CollectionsLink)
                        .Where(col => col.Id == CollectionID).ToArray();
    if (collections.Any())
        return collections.First();

    return await client.CreateDocumentCollectionAsync(database.CollectionsLink,
        new DocumentCollection
        {
            Id = CollectionID
        });
}

Create Documents

Create normal C# objects that represent documents.

Create Team Documents

Team team1 = new Team
{
     Id="t001",
      TeamName="Football team 1",
      Players= new Player[]{
        new Player{ PlayerName="Chervine", PlayerAge=21},
        new Player { PlayerName="Kevin", PlayerAge=21}
      }
};

Team team2 = new Team
{
    Id = "t002",
    TeamName = "Football team 2",
    Players = new Player[]{
        new Player{ PlayerName="Cherv", PlayerAge=21},
        new Player { PlayerName="Kev", PlayerAge=21}
      }
};

Save the documents

To save documents, the method CreateDocumentAsync is used that creates a document as an asynchronous operation.

await client.CreateDocumentAsync(documentCollection.DocumentsLink, team1);
await client.CreateDocumentAsync(documentCollection.DocumentsLink, team2);

The document is now saved.

You may now browse it from the Azure portal. From the dashboard, select your DocumentDB, scroll down to Document Explorer, and select the collections you wish to view.



Read data from the Application

You can use both SQL and LINQ to retrieve data in DocummentDB.

Using SQL

Retrieving one team

team2 = client.CreateDocumentQuery<Team>(documentCollection.DocumentsLink, "SELECT * FROM Teams t WHERE t.TeamName = \"Football team 2\"").AsEnumerable().FirstOrDefault();

Retrieving all teams

foreach (var team in client.CreateDocumentQuery(documentCollection.DocumentsLink,
"SELECT * FROM Teams"))
{
Console.WriteLine("\tRead {0} from SQL", team);
}

Using LINQ

Retrieving one team

team1 = client.CreateDocumentQuery<Team>(documentCollection.DocumentsLink).Where(d => d.TeamName == "Football team 1").AsEnumerable().FirstOrDefault();

Updating a document

You first need to get the document to update, make the changes and replace the document.

dynamic Team2Doc = client.CreateDocumentQuery<Document>(documentCollection.DocumentsLink).Where(d => d.Id =="t002").AsEnumerable().FirstOrDefault();
Team2Doc.TeamName = "UPDATED_TEAM_2";
await client.ReplaceDocumentAsync(Team2Doc);

Delete a document

Document Team3Doc = client.CreateDocumentQuery<Document>(documentCollection.DocumentsLink).Where(d => d.Id =="t003").AsEnumerable().FirstOrDefault();
await client.DeleteDocumentAsync(Team3Doc.SelfLink)

Conclusion

Microsoft Azure DocumentDB is really easy to use and allows for rapid application development.Being able to store heterogeneous JSON documents within DocumentDB and query it using SQL like syntax and LINQ is really great which means that the developer do not have to learn anything new.