Step by step: .NET Core and Azure Cosmos DB

by Carlos Mendible on 25 Jun 2017 » Azure, dotNetCore

Step by step: .NET Core and Azure Cosmos DB is a short post on how to connect to Cosmos DB, save a document and then query to find it.

Let’s start:

1. Create a Cosmos DB account

Create a Cosmos DB account in your Azure subscription. Once created get the URI and the primary Read-write key from the Keys section.

If you need info on how to do this browse to the Create a database account section here:

2. Create a folder for your new project

Open a command promt an run

mkdir cosmosdb

3. Create the project

cd cosmosdb
dotnet new console

4. Add a reference to the Microsoft.Azure.DocumentDB.Core library

Add a reference to the Microsoft.Azure.DocumentDB.Core client library so you are able to talk with Cosmos Db.

dotnet add package Microsoft.Azure.DocumentDB.Core -v 1.3.2

5. Restore packages

You just modified the project dependencies so please restore the packages with the following command:

dotnet restore

6. Modify Program.cs

Replace the contents of the Program.cs file with the following code and remember to change lines 13 and 16 with your account URI and Key

using System;
using System.Linq;
using Microsoft.Azure.Documents;
using Microsoft.Azure.Documents.Client;

namespace cosmosdb
    class Program
        static void Main(string[] args)
            // The endpoint to your cosmosdb instance
            var endpointUrl = "[THE ENPOINT OF YOUR COSMOSDB SERVICE HERE]";

            // The key to you cosmosdb
            var key = "[THE KEY OF YOUR COSMOSDB SERVICE HERE]";

            // The name of the database
            var databaseName = "Students";

            // The name of the collection of json documents
            var databaseCollection = "StudentsCollection";

            // Create a cosmosdb client
            using (var client = new DocumentClient(new Uri(endpointUrl), key))
                // Create the database
                client.CreateDatabaseIfNotExistsAsync(new Database() { Id = databaseName }).GetAwaiter().GetResult();

                // Create the collection
                    new DocumentCollection { Id = databaseCollection }).

                // Create a Student instance
                var student = new Student() { Id = "Student.1", Name = "Carlos", LastName = "Mendible" };

                // Sava the document to cosmosdb
                client.CreateDocumentAsync(UriFactory.CreateDocumentCollectionUri(databaseName, databaseCollection), student)

                Console.WriteLine($"Student was saved in the database with id: {student.Id}");

                // Query for the student by last name
                var query = client.CreateDocumentQuery<Student>(
                        UriFactory.CreateDocumentCollectionUri(databaseName, databaseCollection))
                        .Where(f => f.LastName == "Mendible")

                if (query.Any())
                    Console.WriteLine("Student was found in the cosmosdb database");


    /// <summary>
    /// A simple class representing a Student
    /// </summary>
    public class Student
        public string Id { get; set; }

        public string Name { get; set; }

        public string LastName { get; set; }

7. Build

Build the application with the following command

dotnet build

8. Run

You are good to go so run the application

dotnet run

You can get the code here:

Hope it helps!