Persistance with DocumentDB - HenrikWM/NNUG_GAB2016 Wiki

Initial setup

These assignments use a DocumentDBRepository<T>-class to persist our entities. Its purpose is to provide an API for Create, Read, Update and Delete operations.

It expects to have access to the following appSettings keys provided in HiddenAppSettings.config per API-project (where it's used). Create this config file in your project and base it on the HiddenAppSettings.config.example-file with the following appSettings keys:

  • database: name of the database to contain our collections
  • collection: name of the collection to store entities of type T
  • endpoint: your DocumentDB service endpoint in Azure
  • authKey: your access-key for performing operations against your database

database: enter a name for your DocumentDB database. Suggested name is: nnug-gab2016-<your initials>-docdb

collection: enter a name for your project's entity collection. If you're using DocumentDBRepository<T> as DocumentDBRepository<Employee> in your GAB.Web.EmployeeRecords.Api-project, suggested collection name is: Employees. Similarly for the reports and resource planning APIs, you should have a config in those projects as well and use collection names Reports and ResourcePlans.

The repository class will create the DocumentDB database and each collection for you when you first instantiate and use it.

Retrieving DocumentDB endpoint and authkey settings from the Azure portal

In this guide you will learn how to find and retrieve the endpoint and authkey setting values for your DocumentDB service in the Azure portal.


  • Ensure you have a DocumentDB account. If not, learn how to create an account.
  • Suggested naming convention for a DocumentDB account for these assignments: nnug-gab2016-<your initials>-docdb. E.g.: nnug-gab2016-hwm-docdb.
  • Create a HiddenAppSettings.config-file in your project in Visual Studio to store your secret appSettings. Your app.config or web.config should reference this file: <appSettings file="HiddenAppSettings.config">. See the HiddenAppSettings.config.example for reference.

Steps to retrieve settings

Log into the Azure Portal and click on the All resources menu item in the left menu.

Find your DocumentDB account in the All resources list (Type: DocumentDB Account) and click it.

Click on Settings on the top of the DocumentDB account blade and click on the Keys menu option in the blade that opens to the right.

Copy the value from the URI field into your endpoint appSetting in your HiddenAppSettings.config-file

Copy the value from the PRIMARY KEY field into your authKey appSetting in your HiddenAppSettings.config-file

Congratulations! You should now be able to use your DocumentDBRepository<T>-class to persist entities to your DocumentDB account.

Verify setup after first-use

To verify that the database and collections are created, in the DocumentDB account blade click on your database. Verify that you can see your collections in the Database blade that opens to the right.

⚠️ ** Fallback** ⚠️