Using Microsoft Azure DocumentDB In An ASP.NET MVC Application

Scope

The following article demonstrates use of Microsoft Azure DocumentDB in an ASP.NET MVC Application.

Introduction

Azure DocumentDB is a NoSQL storage service which stores JSON documents natively and provides indexing capabilities along with other interesting features.

The following are some of the key terms used in this article:

Collection

A collection is a named logical container for documents.

A database may contain zero or more named collections and each collection consists of zero or more JSON documents.

Being schema-free, the documents in a collection do not need to share the same structure or fields.

Since collections are application resources, they can be authorized using either the master key or resource keys.

DocumentClient

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

Creating a DocumentDB Account

Please refer to this article to create and setup a DocumentDB Account on Microsoft Azure.

Getting Started

To get started, create a new ASP.NET MVC project in Visual Studio and add the DocumentDB NuGet package by going to Tools NuGet Package Manager > package Manager Console and key in the following:

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





The Web.Config File

Retrieve the endpoint(URI) and the authKey (Primary/Secondary key) from your DocumentDb Account and add them in the Web Config file.

The keys database and collection represents the name of the database and collections that shall be used in your applications respectively.


Create DocumentDB Repository Class

This is where all the codes that shall be used to communicate with Azure DocumentDB shall be found.

1. Retrieve the DatabaseId and CollectionId from the Web.Config file
   
   1. /// <summary>
   2. /// Retrieve the Database ID to use from the Web Config
   3. /// </summary>
   4. private static string databaseId;
   5. private static String DatabaseId
   6. {
   7. get
   8. {
   9. if (string.IsNullOrEmpty(databaseId))
   10. {
   11. databaseId = ConfigurationManager.AppSettings["database"];
   12. }
   14. return databaseId;
   15. }
   16. }
   18. /// <summary>
   19. /// Retrieves the Collection to use from Web Config
   20. /// </summary>
   21. private static string collectionId;
   22. private static String CollectionId
   23. {
   24. get
   25. {
   26. if (string.IsNullOrEmpty(collectionId))
   27. {
   28. collectionId = ConfigurationManager.AppSettings["collection"];
   29. }
   31. return collectionId;
   32. }
   33. }
2. Retrieve the DocumentClient
   
   The document Client provides a client-side logical representation of the Azure DocumentDB service.
   
   This client is used to configure and execute requests against the service.
   
   1. private static DocumentClient client;
   2. private static DocumentClient Client
   3. {
   4. get
   5. {
   6. if (client == null)
   7. {
   8. string endpoint = ConfigurationManager.AppSettings["endpoint"];
   9. string authKey = ConfigurationManager.AppSettings["authKey"];
   10. Uri endpointUri = new Uri(endpoint);
   11. client = new DocumentClient(endpointUri, authKey);
   12. }
   14. return client;
   15. }
   16. }
3. Get the database that shall be used
   
   If no database is found, the method ReadOrCreateDatabase() is called, to verify if the database exist and creates if it does not exist.
   
   1. private static Database database;
   2. private static Database Database
   3. {
   4. get
   5. {
   6. if (database == null)
   7. {
   8. database = ReadOrCreateDatabase();
   9. }
   11. return database;
   12. }
   13. }
   15. private static Database ReadOrCreateDatabase()
   16. {
   18. var db = Client.CreateDatabaseQuery()
   19. .Where(d => d.Id == DatabaseId)
   20. .AsEnumerable()
   21. .FirstOrDefault();
   23. if (db == null)
   24. {
   25. db = Client.CreateDatabaseAsync(new Database { Id = DatabaseId }).Result;
   26. }
   28. return db;
   29. }
4. Get the DoucmentCollection which will be used
   
   A collection is a named logical container for documents.
   
   A database may contain zero or more named collections and each collection consists of zero or more JSON documents.
   
   If the required collection is not found, the method ReadOrCreateCollection is called that creates it.
   
   1. private static DocumentCollection collection;
   2. private static DocumentCollection Collection
   3. {
   4. get
   5. {
   6. if (collection == null)
   7. {
   8. collection = ReadOrCreateCollection(Database.SelfLink);
   9. }
   11. return collection;
   12. }
   13. }
   15. private static DocumentCollection ReadOrCreateCollection(string databaseLink)
   16. {
   18. var col = Client.CreateDocumentCollectionQuery(databaseLink)
   19. .Where(c => c.Id == CollectionId)
   20. .AsEnumerable()
   21. .FirstOrDefault();
   23. if (col == null)
   24. {
   25. col = Client.CreateDocumentCollectionAsync(databaseLink, new DocumentCollection { Id = CollectionId }).Result;
   26. }
   28. return col;
   29. }