{"id":80384,"date":"2018-08-15T15:52:04","date_gmt":"2018-08-15T15:52:04","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=80384"},"modified":"2022-04-24T21:31:21","modified_gmt":"2022-04-24T21:31:21","slug":"developing-client-applications-using-the-sdk-and-azure-cosmos-db-emulator","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/development\/dotnet-development\/developing-client-applications-using-the-sdk-and-azure-cosmos-db-emulator\/","title":{"rendered":"Developing Client Applications Using the SDK and Azure Cosmos DB Emulator"},"content":{"rendered":"

In this article, I am going to describe how to use the .NET SDK to build Cosmos DB client applications with the SQL API. You will see how .NET SDKs are useful for efficient programming and how to leverage them to perform various operations on Azure Cosmos DB. My last article<\/a> covered core concepts in Cosmos DB and how to setup the Local Emulator to imitate creating collections and documents. This article will focus on creating and querying the collections and documents through the .NET SDK using C# code. It will also go over how to consume the Azure Cosmos DB Emulator through a client application.<\/p>\n

Why Use an SDK?<\/h2>\n

Let\u2019s begin with a brief overview of the .NET SDK and its importance in the world of application development. Microsoft Azure provides a platform that can be used to build highly scalable and reliable applications with ease. Like almost every other service in the cloud, Cosmos DB supports building web-scale applications.<\/p>\n

You might be aware that almost every service on Azure uses REST (Representational State Transfer) APIs that supports HTTP operations. These HTTP requests provide an ability to create, update, delete and retrieve access to a service\u2019s resources. You can use any HTTP client to perform any operation on Cosmos DB as long as you use the correct resource URL to point to a valid Cosmos DB resource you want to work on and the HTTP headers contain the proper authentication. The most primitive way to access the resources in the Cosmos DB is to issue REST calls, these REST requests are very tedious to create. You will have to keep track of very small details such as constructing a proper header messages and the body of the message so that it is accepted by the receiving Azure services. Additionally, you will also have to take care of deconstructing the responses received from the services.<\/p>\n

To make a developer\u2019s life more hassle-free, we have SDKs. As defined on Microsoft Documentation, .NET\/.NET Core Software Development kit (SDK) is a set libraries and tools that allows developers to create applications and libraries. Today Microsoft provides SDKs for .NET\/.Net Core, Python, Node.JS and JAVA. If you are developing an application on any of these platforms, then using the SDK makes your development experience much smoother as compared to making the REST and HTTP calls. SDKs abstract away the low-level details. Behind the scenes SDKs will take care of setting up the HTTP headers, making the REST calls and deconstructing the response back from Cosmos DB.<\/p>\n

Let\u2019s first go over the main components that we will be heavily relying on to create an application which connects and performs various operations on Cosmos DB emulator. In the next section, I will give you a brief overview of these components and you will see how they are helpful for creating a client .NET application.<\/p>\n

What\u2019s Needed to Create the Application?<\/h2>\n

This application is not difficult to create, but it relies on a handful of technologies and techniques described in this section.<\/p>\n

<\/a><\/a><\/a><\/a>Azure Cosmos DB .NET SDK – The<\/strong> Azure Cosmos DB \/ Document DB (SQL) API.NET SDK<\/strong> added to your project through the NuGet Package Manager<\/em>.<\/p>\n

DocumentClient instance – <\/strong>For accessing the Cosmos DB account through your client application, you will need to create a DocumentClient instance. You will have to supply endpoint and keys to the Cosmos DB account to the DocumentClient constructor. Once you have the DocumentClient, instance you simply call methods to perform various operations on the database such as Create\/Modify\/Delete Databases and Collections, Query Documents and Stored Procedures.<\/p>\n

\n

NOTE: See my previous article<\/a> on setting up a Cosmos DB database in the local Cosmos DB Emulator.<\/em><\/p>\n<\/div>\n

Asynchronous operations –<\/strong> Post Operations to the Cosmos DB will be Asynchronous so the client code does not get blocked waiting for Cosmos DB after issuing requests. This article will use the useTask<\/strong> Parallel Library\u2019s task objects as well as the async<\/strong> and await<\/strong> keywords. Let me give you a brief overview of what exactly async<\/strong> and await<\/strong> are.<\/p>\n

Async<\/strong> and await<\/strong> are the main keywords used in asynchronous programming. Through asynchronous programming you can make your application much more responsive, and it also helps in reducing performance bottlenecks. Using async\/await you can write asynchronous code that looks synchronous. Your code will wait for the method to finish its job even though, normally, it wouldn\u2019t because this is asynchronous call. For async to work you have to mark the method as having asynchronous behavior with the async<\/strong> keyword. You will have to call these methods using await<\/strong> keywords. Remember that every async<\/strong> method always returns a Task<\/strong> object. If that method has nothing to return then, it just returns the Task<\/strong> object. For instance, in the code below, the Foo()<\/strong> method is marked as async.<\/strong> Since it returns nothing, the return type is the plain Task<\/strong> object, which is practically same as returning a void. If you have some value to return such as bool<\/strong> or string<\/strong>, then you will use a generic form of Task<\/strong> object such as Task<bool><\/strong> or Task<string>.<\/strong><\/p>\n

<\/p>\n

LINQ: <\/strong>Language Integrated-Query can be used to write a query expression with standard query operators in a declarative way in .NET supported programming languages. If you prefer to use LINQ over SQL then, .NET SDK supports a LINQ provider that can translate LINQ queries into Cosmos DB SQL for execution.<\/p>\n

I assume at this point you might have a basic idea of all the important ingredients you need to cook your recipe, i.e. to develop a Client application and perform various operations on Cosmos DB.<\/p>\n

Creating an Application with the Azure Cosmos DB .NET SDK:<\/h2>\n

Here I am going to demonstrate how to create a .Net console application and use the Azure Cosmos DB<\/strong> .NET SDK. Start with a new Console application in Visual studio. For this go to File -> New -> Project<\/em> which opens a new window. Select Visual C# -> Console App (.NET Framework). <\/em>Provide a name for your Application, such as CosmosAppDemo<\/em>.<\/p>\n

\"C:\\Users\\spande\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\A22.jpg\"<\/p>\n

Once you click OK,<\/em> you will see a new project is created. First add keys to the app.config<\/em> file and then grab the the Endpoint and Primary key from the Local Emulator so that you can update and store them at the right place in app.config <\/em>file.<\/p>\n

  <appSettings>\r\n    <add key=\"CosmosDBEndpointAddress\" value=\"\"\/>\r\n    <add key=\"CosmosDBPrimaryKey\" value=\"\"\/>\r\n  <\/appSettings><\/pre>\n
\"C:\\Users\\spande\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\A23.jpg\"<\/p>\n
To get the Endpoint address and Primary key, you need to have Azure Cosmos DB Emulator running. Search for and run the Azure Cosmos DB Emulator. Once it\u2019s running, you can access your Azure Cosmos DB Emulator using the local host address https:\/\/localhost:8081\/_explorer\/index.html<\/a>. Copy the URI and Primary Key from the Emulator and paste them in the respective value fields you just added to the keys.<\/p>\n
<\/p>\n
After you add the key, your app.config<\/em> will look something like this:<\/p>\n
\"C:\\Users\\spande\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\A25new.jpg\"<\/p>\n
Now to access the settings you just added to app.config, <\/em>you will need to add a reference to System.Configuration<\/em> to the project. To do this go to the Solution Explorer <\/em>Window, right-click on References. <\/em>Click Add reference<\/em> and expand Assemblies. <\/em>Select Framework<\/em> from the top right corner. Scroll down and select System.Configuration<\/em>.<\/p>\n
\"C:\\Users\\spande\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\A2SysrefSelectEdited.jpg\"<\/p>\n
Once you click OK<\/em> you will see System.Configuration<\/em> added to the project\u2019s references as shown below.<\/p>\n
\"C:\\Users\\spande\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\A2FinalSysyrefedited.jpg\"<\/p>\n
Next, you\u2019ll need to get the Azure Cosmos DB .NET SDK in place which you can grab from NuGet. Right-click the project in Solution Explorer<\/em> and select Manage NuGet Packages<\/em>. Look for the package with the title Microsoft.Azure.DocumentDB<\/em>. In this article you are going to use SQL APIs. Make sure you select a package that says SQL API<\/em> in the description. You might have noticed that the name of the package still uses DocumentDB<\/em> which is now called Cosmos DB. This might get changed in future. Although the API name is going to be changed at some point, it is still being called Document DB in order to maintain backwards compatibility with existing applications.<\/p>\n
<\/p>\n
Once you select the package, click the Install<\/em> button. You will see that the installation pulls Newtonsoft.Json<\/em> which is a JSON serializer and also the Microsoft.Azure.DocumentDB.1.22.0<\/em> package. Now just click OK<\/em> and accept the Licence aggrement.<\/p>\n
\"C:\\Users\\spande\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\A2NugetInstallingEdited.jpg\"<\/p>\n
After the installation has finished, you will see the assembly reference in your project.<\/p>\n
\"C:\\Users\\spande\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\A2AssemblyReferenceedited.jpg\"<\/p>\n
Using Azure Cosmos DB .NET SDK to work with Cosmos DB Emulator:<\/h2>\n
For making you aware of all the features available in the CosmosDemoApp<\/em> project, I have created a menu option so that you can easily pick whether you want to work on the Database methods, Collection methods, or Document methods. When you have created the project, you will notice that the Program.cs<\/em> class file is auto created. This project will contain a Menu option which will help you navigate through the app. This demo first creates the Database and uses that Database to create Collection. Then it creates a new Document using these newly created Database and Collection.<\/p>\n
From Cosmos DB, the three important components that you are going to create and display in this demo are Databases, Collections, and Documents. Create a separate folder called DemoClasses<\/em> in the project and add class files DatabaseOperations.cs<\/em> for Database methods, CollectionOperations.cs<\/em> for Collection Methods and DocumentOperations.cs<\/em> for Document methods. Your project should look like the figure below.<\/p>\n
\"C:\\Users\\spande\\AppData\\Local\\Microsoft\\Windows\\INetCache\\Content.Word\\A22FOlderStructreed.jpg\"<\/p>\n
The class files are invoked these Class files depending on what input user provides. The code in Program.cs,<\/em> shown below, is self-explanatory. I won\u2019t go into much details of this code as we need to focus more on Database, Collection and Document methods in details.<\/p>\n
\n
Note: I have shown the output at each stage of the program, but I would recommend that if you are running the code on your computer that you create all the Class files beforehand with the final code so that you don\u2019t see many errors during runtime. (You can download the class files from the link at the bottom of the article.) Also, make sure you have your local emulator running.<\/em><\/p>\n<\/div>\n
Here is the code from the Program.cs<\/em> file:<\/p>\n
using System;\r\nusing System.Collections.Generic;\r\nusing System.ComponentModel;\r\nusing System.Configuration;\r\nusing System.Linq;\r\nusing System.Text;\r\nusing System.Threading.Tasks;\r\nusing CosmosAppDemo.<\/a>DemoClasses;\r\nusing Microsoft.Azure.Documents;\r\nusing Microsoft.Azure.Documents.Client;\r\nnamespace CosmosAppDemo\r\n{\r\n    class Program\r\n    {\r\n        private static IDictionary<string, Func<Task>> methods;\r\n        static void Main(string[] args)\r\n        {\r\n            methods = new Dictionary<string, Func<Task>>();\r\n            methods.Add(\"A\", DatabaseOperations.Run);\r\n            methods.Add(\"B\", CollectionOperations.Run);\r\n            methods.Add(\"C\", DocumentOperations.Run);\r\n            Task.Run(async () =>\r\n            {\r\n                MenuOptions();\r\n                while (true)\r\n                {\r\n                    Console.Write(\"Choice: \");\r\n                    var input = Console.ReadLine();\r\n                    var demoId = input.ToUpper().Trim();\r\n                    if (methods.Keys.Contains(demoId))\r\n                    {\r\n                        var methodId = methods[demoId];\r\n                        await ExecuteDemo(methodId);\r\n                    }\r\n                    else if (demoId == \"Q\")\r\n                    {\r\n                        break;\r\n                    }\r\n                    else\r\n                    {\r\n                        Console.WriteLine($\"?{input}\");\r\n                    }\r\n                }\r\n            }).Wait();\r\n        }\r\n        private static void MenuOptions()\r\n        {\r\n            Console.WriteLine(@\"Select an option\r\n                    A Create or Display Databases\r\n                    B Create or Display Collections\r\n                    C Create or Display Documents\r\n                    Q Quit\r\n                    \");\r\n        }\r\n        private async static Task ExecuteDemo(Func<Task> demoMethod)\r\n        {\r\n            try\r\n            {\r\n                await demoMethod();\r\n            }\r\n            catch (Exception ex)\r\n            {\r\n                var message = ex.Message;\r\n                while (ex.InnerException != null)\r\n                {\r\n                    ex = ex.InnerException;\r\n                    message += Environment.NewLine + ex.Message;\r\n                }\r\n                Console.WriteLine($\"Error: {ex.Message}\");\r\n            }\r\n            Console.WriteLine();\r\n            Console.Write(\"Press any key to continue...\");\r\n            Console.ReadKey(true);\r\n            Console.Clear();\r\n            MenuOptions();\r\n        }\r\n    }\r\n}<\/pre>\n
Once you run the app, this code will produce results in the Console Window:<\/p>\n
<\/p>\n
Database operations<\/h2>\n
First, I am going to demonstrate how different operations such as creation, deletion and displaying the Cosmos DB database is done. In the below code, I have created different methods to perform easy operations such as DisplayDatabases(client) <\/strong>to display, CreateNewDatabase(client) <\/strong>to create a new database, and DeleteDatabase(client) <\/strong>to delete the database from Cosmos DB. These are very basic tasks, but you will be using such tasks for consuming almost every Azure service.<\/p>\n
The code itself is very descriptive, but let me give you a brief overview of the implementation. You are going to create a Document Client object by passing the Cosmos DB endpoint details and primary key to DocumentClient<\/strong>. It good practice to create just one instance of this object and use it wherever it\u2019s needed. This will save several lines of code, and you don\u2019t have to keep on creating and deleting the objects. Here you are using the using<\/strong> keyword that will make sure it is properly disposed of when execution of the inside code is done. Here are the three Main methods which are implemented in the below code:<\/p>\n