What is Azure IoT Hub?

In my last article, we learned about the Azure device provisioning service, which allows us to manage IoT devices. If you have not read my previous article about the Azure device provisioning service yet, then please read it using the following link:

Now we have a platform to manage the IoT devices, but what about connecting the devices to some platform and getting the data from those connected devices? We must connect the device to some gateway platform to establish a secure connection between the cloud and the device to exchange the data. So, in this article, we will learn about the Azure IoT hub and the role of the IoT hub in managing the IoT devices' communication and telemetry data.

What is Azure IoT?

Azure IoT is the IoT gateway for IoT devices, which allows bi-directional communication between IoT devices and the cloud and from the cloud to IoT devices. Azure IoT can process the millions of IoT devices and route the messages to specific data storage platforms.

Key Advantages of Azure IoT

  • Built-in UI to manage and monitor the IoT devices
  • Capture entire device lifecycle events using the device lifecycle change event feature.
  • Allows us to upgrade the firmware of single or bulk numbers of devices using the automatic device management feature.
  • Built-in support for bidirectional communication between IoT devices and the cloud
  • The IoT hub allows us to connect edge devices and IoT devices, which means the IoT hub is capable of connecting low-powered and high-processing devices.
  • IoT devices can send telemetry data as well as connect devices over a network using the AMQP, MQTT, and HTTPS protocols to the Azure IoT hub.
  • The Azure IoT Hub has multiple device authentication mechanisms, including X509, TPM, and symmetric keys.
  • The message routing feature helps to route messages to a specific data store and data processing platform.
  • built-in support for uploading the file for a specific device, which can be used for device upgradation or storing device process-related information.
  • Azure IoT hub IoT Hub allows us to send commands to the device, which can help change the behaviour of the device using the "Cloud to Device" message feature.
  • provides the device-twinning feature for storing metadata or other information about IoT devices.
  • Azure IoT Hub is intended to be a secure platform for device communication and authentication, utilising communication protocols AMQP, MQTT, and HTTPS as well as authentication mechanisms such as X509, TPM, and symmetric keys.
  • The IoT hub provides various options to establish bi-directional communication between the cloud and devices programmatically with SDKs in C#, Java, Python, Node.js, and Android, as well as an API for the IoT hub.
  • allows you to enable or disable the connected IoT devices.
  • built-in support for routing and filtering the messages to the other services.

Creating An Azure IoT Hub Using Azure Portal


Azure IoT Hub can be created using:
  • Azure CLI
  • SDK
  • API
  • ARM
  • Azure portal 
In this article, we will be creating an IoT hub using the portal so we can avoid confusion for beginners. Now let’s start creating the azure IoT hub step-by-step via the Azure portal.

Prerequisites

 
To create any Azure service, we need an active Azure subscription, whether it’s a paid or trial subscription. I am assuming you have an active Azure subscription

Step 1: Go to the Azure Portal

Navigate to the portal.azure.com using your browser and login into the portal with valid credentials, as shown in the following image:


After a successful login, the page will be redirected to the Azure portal, by default, the dashboard page is set as:

Step 2: Create Azure IoT

Find the create resource option which can be found on the left top side of the portal as shown in the following image or follow any other option which you may know to create the resource (service) in the Azure portal:



Click on the left side option to create a resource & type IoT hub into the populated search box, it will pop up the following screen as:



As shown in the preceding image click on the create button, it will show the following screen:



Provide required details as shown in the preceding image:
  • Subscription: Choose the available azure subscription which you want to use for creating service from drop-down list
  • Resource Group: Choose an existing resource group or create a new resource group that you may want to use.
  • Region: Choose the deployment location for IoT hub device provisioning from the given list. However, the device provisioning service is global and associated with any specific location, but you must specify a location for the resource group where the metadata associated with the service profile will reside.
  • IoT Hub Name: Name of the IoT hub service which must contain only alphanumeric characters or a hyphen.
After providing all the basic required details, click to review and create the IoT hub, which skips the remaining steps, or click to choose the next step, networking. It shows the following screen to configure networking:



In the above image, we choose the connectivity method for the IoT hub which decides which network the devices can connect to the IoT hub, there are three methods:
  • Public Endpoint all Network
  • Public Endpoint selected IP addresses
  • Private Endpoint 
Public EndPoint all Network

This option allows us to connect devices to the IoT hub on all public networks for whoever has access to public URI and the required credentials.

Public Endpoint selected IP addresses

Even you have a public endpoint (URI) but want to restrict devices, you should connect from a specific IP address. Then you can define the range of IP addresses. The IoT hub allows you to connect only to devices that fall within the defined IP address range. This option gives the useful feature to allow only known networks to connect to the devices

Private EndPoint

This is the URI or endpoint which allows us to connect devices over the private network, which gives the robust security between devices and IoT hub communication
Once you choose your intended connectivity method, click on the next step which shows the step to configure the scalability of the IoT hub as:


The preceding management step allows us to define the scalability and security of the IoT hub with the help of the following options:
  • Pricing and Scale Tier
  • IoT Hub Units
  • Defender

Pricing and Scale Tier

 
There are different types of pricing and scale tiers that decide how many messages the device sends to the IoT hub per day and what feature does it supports. The features and message frequency of IoT hub can differ based on the pricing and scale tier. The pricing tiers are categorized as:


Free Tier

 
The F1 is the free tier by using you can use the free tier of IoT hub for your learning and check how IoT hub works. it allows 8000 messages per day with limited feature

Basic Tier


The basic tier is sub-categorized into the three types as
  • B1
  • B2
  • B3
Basic tiers are suitable for development activities but you can not get all the features in this pricing and scale tier.


Standard Tier


The standard pricing and scale tier provides the most advanced features and scales for the incoming IoT messages, The standard tier subcategorized into the three types as:
  • S1
  • S2
  • S3 
These tiers are most suitable for a production environment where hyper scalability and advanced security are required. Once you choose the configuration for the IoT hub, click on the next step tags, which shows the following screen:



The tagging helps to identify or categorize the services across the line of applications, after providing tags details, click on the next step review and create, it will show the following screen to review the details before creating the service:


After reviewing details, click on the create button, it will take some time to create the service. Once the service is created, the status can be notified on the notification icon as shown in the following image: 


Now click on the Go to resource button, you will be redirected to the newly created IoT hub service as shown in the following image:


Let’s learn about the preceding Azure IoT hub key sections in brief, listed below:
  • Overview
  • Certificates
  • Built-in Endpoints
  • Query Explorer
  • IoT Devices
  • Automatic Device Management
  • Messaging
  • Security
  • Monitoring
Overview
 
The overview section of the IoT hub is like a dashboard where you can see an overview of the service details, including the charts for incoming messages, status, etc.

Certificates
 
This section allows to add and save the device certificates which can be assigned to the devices during creating or adding the devices to the IoT hub.

Built-in Endpoints
 
This section contains the details which allow us to use the IoT hub as an event hub. The event hub compatible connectionString gives almost the same functionality as an event hub without creating any instance of the event hub.

Query Explorer
 
This section allows us to query devices that reside in the IoT hub. This feature is useful to query any device from the millions of devices from the IoT hub.

IoT Devices
 
This section lets you add the different types of IoT devices and related configuration.

Automatic Device Management
 
This section allows us to upgrade the firmware of individual or bulk of IoT devices based on the properties of the device such as tags or deviceId.

Messaging
 
This feature allows to capture the IoT device messages and their related events also you can route the messages to any other service such as data store etc.

Security
 
This section allows to secure the IoT devices using the IoT defender feature and create the security-related alerts

Monitoring

This section allows to monitor the logs related to the IoT hub, you can set any filter or rule for monitoring and create the alerts

Summary

I hope this article was useful for understanding the basics of the Azure IoT hub service.

Articles you may interested

How to use Azure Cosmos DB Locally for Development

In this article, we will learn how to use the Azure Cosmos DB for local development without consuming cloud resources with a CRUD operation example. This method reduces the cost of testing numerous scenarios during development. 

Step 1: Set up Prerequisites

To use Azure Cosmos DB for local development and to perform CRUD operations in the Azure Cosmos DB, set up the following prerequisites: 

Azure Cosmos DB Emulator (offline)

The Azure Cosmos DB Emulator currently does not have support for all the NoSQL APIs, but it will support the most commonly used NoSQL APIs, such as the SQL API and Mongo DB API, and in the future it may also support all the Cosmos DB APIs.

The following is the link to download the Azure Cosmos DB Emulator.

After clicking on the link, the official Microsoft documentation website gets opened, from which you can find and install the latest version of the Azure Cosmos DB Emulator.

Step 2: Create Azure Cosmos DB 

In this article, we are going to use the Azure Cosmos DB emulator instead of a Cloud Azure Cosmos DB account. If you are new to Azure Cosmos DB, please read the articles below to learn how to create an Azure Cosmos DB account.
We are using the Azure Cosmos DB emulator in this article. search for the Azure Cosmos DB emulator from the search bar of the window once you download and install the emulator, which looks like the following:



The preceding image shows the Azure CosmosDB Account of the emulator, which will provide the same features as the Cloud Azure CosmosDB Account for development. Now click on the explorer and create the database and container. The explorer will then look like this:



We are storing the employee basic data in the Azure CosmosDB, and we are planning to use Department as a partition key and ID as the unique id for our employee records.

Note:
  • The ID and Department properties should be part of your backend input while inserting or updating the records; otherwise, you will get the exceptions.
I hope you have completed the required setup as explained in this article, including the creation of the Azure Cosmos account and database.

Step 3: Create ASP.NET Core web api Project

  1. Start then  All Programs and select "Microsoft Visual Studio".
  2. Once the Visual Studio Opens, Then click on Continue Without Code.
  3. Then Go to Visual Studio Menu, click on File => New Project then choose ASP.NET Core Web Api Project Template.
  4. Then define the project name, location of the project, then click on the next button.
  5. On the next screen, provide the additional details: framework, authentication type, and check the Enable Open API Support checkbox as shown below.


The preceding steps will create the ASP.NET Core Web API application and solution explorer. It will look like what is shown in the following image.



Step 4: Add Microsoft.Azure.Cosmos Nuget Package Reference

The Microsoft.Azure.Cosmos is the the latest nuget package to interact with the Azure cosmos DB. The Microsoft.Azure.Cosmos supports the basic to custom and complex database operations, follow the following steps to add the Nuget package.

  1. Right click on the Solution Explorer, find Manage NuGet Package Manager and click on it
  2. After as shown into the image and type in search box Microsoft.Azure.Cosmos
  3. Select Microsoft.Azure.Cosmos as shown into the image, 
  4. Choose version of Microsoft.Azure.Cosmos library and click on install button


I hope you have followed the same steps and installed the Microsoft.Azure.Cosmos nuget package.The next step is to delete the default controller and model class so we can start from scratch.


Step 5:Create the Model Class

  • First, delete the default model class, which is created outside the folder structure, so we can start from scratch. 
  • Next, create the folder named Model by right clicking on the solution explorer.
  • Create the model class Employee Model by right clicking on the Model folder, as shown in the following image


Now open the EmployeeModel.cs class file and add the following code.

EmployeeModel.cs

namespace EmployeeManagement.Model
{
    public class EmployeeModel
    {
        public string? id { get; set; }
        public string? Name { get; set; }
        public string? Country { get; set; }
        public string? City { get; set; }       
        public string? Department { get; set; }
        public string? Designation { get; set; }
        public DateTime? JoiningDate { get; set; }

    }
}

Step 6: Add the Controller

Create the Empty API Controller class EmployeeController by right clicking on the Controller folder as shown in the following image.



After adding the model class and API controller class, the solution explorer will look like the following:




Now open the EmployeeController.cs file and add the add the following configuration.
  • Define the following route at controller level, so that we can add the multiple Get, Post, Put, or Delete and avoid the name ambiguity exception.
    [ApiController]
    [Route("[api/[controller]/[action]]")]
    public class EmployeeController : ControllerBase
    {
    }

  • Declare the following variable and set the Azure Cosmos DB configuration by copying the details from step 2.
    [ApiController]
    [Route("api/[controller]/[action]")]
    public class EmployeeController : ControllerBase
    {
       
        // Cosmos DB details, In real use cases, these details should be configured in secure configuraion file.
        private readonly string CosmosDBAccountUri = "https://localhost:8081/";
        private readonly string CosmosDBAccountPrimaryKey = "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==";
        private readonly string CosmosDbName = "EmployeeManagementDB";
        private readonly string CosmosDbContainerName = "Employees";
}

Step 7: Create Method to Add Employee

Add the following code into the EmployeeController.cs class to Add the employees into the CosmosDB. This method takes input values using  the EmployeeModel class. 

        [HttpPost]
        public async Task<IActionResult> AddEmployee(EmployeeModel employee)
        {
            try
            {
                var container = ContainerClient();
                var response = await container.CreateItemAsync(employee, new PartitionKey(employee.Department));

                return Ok(response);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
               
        }


As explained in step 2, we are passing the ID and Department as a partition key as part of the employee input payload while adding the employee details. These parameters must be part of the input parameter payload.

Step 8:  Create Method to Get Employees

Add the following code into the EmployeeController.cs class to get all the employees from the Cosmos database.

        [HttpGet]
        public async Task<IActionResult> GetEmployeeDetails()
        {
            try
            {
                var container = ContainerClient();
                var sqlQuery = "SELECT * FROM c";
                QueryDefinition queryDefinition = new QueryDefinition(sqlQuery);
                FeedIterator<EmployeeModel> queryResultSetIterator = container.GetItemQueryIterator<EmployeeModel>(queryDefinition);


                List<EmployeeModel> employees = new List<EmployeeModel>();

                while (queryResultSetIterator.HasMoreResults)
                {
                    FeedResponse<EmployeeModel> currentResultSet = await queryResultSetIterator.ReadNextAsync();
                    foreach (EmployeeModel employee in currentResultSet)
                    {
                        employees.Add(employee);
                    }
                }

                return Ok(employees);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
           
        }


This example is not good practise since we are fetching all the employees without paging or a partition key filter, but we are doing this to learn how it works without making it complicated. In the next article, I will show how to get a list of records with the paging.

Step 9: Create Method to Get Employee by ID

Create the GetEmployeeDetailsById method in the EmployeeController.cs and add the following code to get the employee by employeeId and partition key from the Cosmos database.


        [HttpGet]
        public async Task<IActionResult> GetEmployeeDetailsById(string employeeId,string partitionKey)
        {

            try
            {
                var container = ContainerClient();
                ItemResponse<EmployeeModel> response = await container.ReadItemAsync<EmployeeModel>(employeeId, new PartitionKey(partitionKey));
                return Ok(response.Resource);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }

        }

Step 10: Create Method to Update Employee

Create the UpdateEmployee method in the EmployeeController.cs and add the following code to update  the employee by employeeId and partition key.

The CosmosDB does not support the partial update feature; rather, it actually replaces the existing item by getting the document to be updated and sending the same details to the database after fields to change or update.

       [HttpPut]
        public async Task<IActionResult> UpdateEmployee(EmployeeModel emp,string partitionKey)
        {

            try
            {

                var container = ContainerClient();
                ItemResponse<EmployeeModel> res = await container.ReadItemAsync<EmployeeModel>(emp.id, new PartitionKey(partitionKey));

                //Get Existing Item
                var existingItem = res.Resource;

                //Replace existing item values with new values 
                existingItem.Name = emp.Name;
                existingItem.Country = emp.Country;
                existingItem.City = emp.City;
                existingItem.Department = emp.Department;
                existingItem.Designation = emp.Designation;

              var updateRes=  await container.ReplaceItemAsync(existingItem, emp.id, new PartitionKey(partitionKey));

                return Ok(updateRes.Resource);

            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
          
        }

Step 11: Create Method to Delete Employee

Create the DeleteEmployee method in the EmployeeController.cs and add the following code to delete the employee by employeeId and partition key.

        [HttpDelete]
        public async Task<IActionResult> DeleteEmployee(string empId, string partitionKey)
        {

            try
            {

                var container = ContainerClient();
               var response= await container.DeleteItemAsync<EmployeeModel>(empId, new PartitionKey(partitionKey));
                return Ok(response.StatusCode);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
        }

    }

The entire code of the EmployeeController.cs class file will look like the following after adding all the methods together:

EmployeeController.cs

using EmployeeManagement.Model;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;

namespace EmployeeManagement.Controllers
{
    [ApiController]
    [Route("api/[controller]/[action]")]
    public class EmployeeController : ControllerBase
    {
       
        // Cosmos DB details, In real use cases, these details should be configured in secure configuraion file.
        private readonly string CosmosDBAccountUri = "https://localhost:8081/";
        private readonly string CosmosDBAccountPrimaryKey = "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==";
        private readonly string CosmosDbName = "EmployeeManagementDB";
        private readonly string CosmosDbContainerName = "Employees";


        /// <summary>
        /// Commom Container Client, you can also pass the configuration paramter dynamically.
        /// </summary>
        /// <returns> Container Client </returns>
        private  Container  ContainerClient()
        {

            CosmosClient cosmosDbClient = new CosmosClient(CosmosDBAccountUri, CosmosDBAccountPrimaryKey);
            Container containerClient = cosmosDbClient.GetContainer(CosmosDbName, CosmosDbContainerName);
            return containerClient;
           
        }


        [HttpPost]
        public async Task<IActionResult> AddEmployee(EmployeeModel employee)
        {
            try
            {
                var container = ContainerClient();
                var response = await container.CreateItemAsync(employee, new PartitionKey(employee.Department));

                return Ok(response);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
               
        }

        [HttpGet]
        public async Task<IActionResult> GetEmployeeDetails()
        {
            try
            {
                var container = ContainerClient();
                var sqlQuery = "SELECT * FROM c";
                QueryDefinition queryDefinition = new QueryDefinition(sqlQuery);
                FeedIterator<EmployeeModel> queryResultSetIterator = container.GetItemQueryIterator<EmployeeModel>(queryDefinition);


                List<EmployeeModel> employees = new List<EmployeeModel>();

                while (queryResultSetIterator.HasMoreResults)
                {
                    FeedResponse<EmployeeModel> currentResultSet = await queryResultSetIterator.ReadNextAsync();
                    foreach (EmployeeModel employee in currentResultSet)
                    {
                        employees.Add(employee);
                    }
                }

                return Ok(employees);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
           
        }
        [HttpGet]
        public async Task<IActionResult> GetEmployeeDetailsById(string employeeId,string partitionKey)
        {

            try
            {
                var container = ContainerClient();
                ItemResponse<EmployeeModel> response = await container.ReadItemAsync<EmployeeModel>(employeeId, new PartitionKey(partitionKey));
                return Ok(response.Resource);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }

        }
        [HttpPut]
        public async Task<IActionResult> UpdateEmployee(EmployeeModel emp,string partitionKey)
        {

            try
            {

                var container = ContainerClient();
                ItemResponse<EmployeeModel> res = await container.ReadItemAsync<EmployeeModel>(emp.id, new PartitionKey(partitionKey));

                //Get Existing Item
                var existingItem = res.Resource;

                //Replace existing item values with new values 
                existingItem.Name = emp.Name;
                existingItem.Country = emp.Country;
                existingItem.City = emp.City;
                existingItem.Department = emp.Department;
                existingItem.Designation = emp.Designation;

              var updateRes=  await container.ReplaceItemAsync(existingItem, emp.id, new PartitionKey(partitionKey));

                return Ok(updateRes.Resource);

            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
          
        }

        [HttpDelete]
        public async Task<IActionResult> DeleteEmployee(string empId, string partitionKey)
        {

            try
            {

                var container = ContainerClient();
               var response= await container.DeleteItemAsync<EmployeeModel>(empId, new PartitionKey(partitionKey));
                return Ok(response.StatusCode);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
        }

    }
}

Now, we have all the code and required configuration to work with Azure CosmosDB in our sample application.

Step 12: Run the ASP.NET Core API Application

Now press Keyboard F5 or the Visual Studio Run button to run the application. After running the application, the following screen will be shown in the browser with swagger UI having all the methods which we have created in our ASP.NET core web API, as shown in the following screenshot:


Now, we will test the functionality by using the Swagger UI, but you can use Postman or any other tool to execute the API endpoints.

Step 13: Azure Cosmos DB CRUD Demo 

Watch the following animated image to see how the insert, read, update, and delete operations of Azure Cosmos DB work.

Add Employees


Get List of Employees and Employee by Id




Update the Employee


Delete the Employee by Id




Summary

I hope, from all the examples above, you have learned how to use the Azure Cosmos DB for local development without consuming cloud resources with a CRUD operation example. If you like it, share it with your friends and subscribe to the blog and YouTube channel for more articles.

Deploy ASP.NET MVC Application on Local IIS

In my previous articles, we learned how to create an ASP.NET MVC application and how to publish an ASP.NET MVC application. Now in this article, we will learn how to deploy an ASP.NET MVC application on local IIS. Hosting is required to make any application accessible to the end-user publicly on the web. So, in this article, we will learn how to host ASP.NET MVC applications in IIS 10. The following steps are required to host any application:
.

If you don't know how to create, develop, and publish an ASP.NET MVC application, then please refer to the following step-by-step tutorial.
I hope you have learned the required steps for developing and publishing an ASP.NET MVC application. Now let's start hosting MVC applications on IIS.

Move the published code on Hosting Server

Copy the "Published files" which we have seen in our previous article Publishing an ASP.NET MVC Application Using File System and paste those on respective servers where you want to host the ASP.NET MVC application. In our last article we have published code in the E drive of my server, as shown in the following image .



Open IIS Manager

Now, open the IIS Manager from Windows menu or in any other ways you have known.

 

The above image is of IIS 10 Manager of my Windows 10 machine. The view as well as options might be different on your machine depending on the OS version.

Add Website to host an ASP.NET MVC application

Right click on "Site" in IIS and click on add new website, as shown in the following screenshot.


After clicking on "Add Website" option, it displays the following configuration window.


I hope you understood the preceding configuration by highlighted text.

Define Site Name & Application Pool

Define the site name which will be useful to uniquely identify the site within the IIS server. After specifying the site name, choose the application pool from available pools. You can even create a custom application pool with any desired name. Currently, our IIS manager has the following application Pools.

 

Choose the application pool depending on your application configuration. In this article, we are going to choose DefaultAppPool.

Browse and select Published Folder path

Now, choose the physical location of published code files by clicking on "Browse" button, as shown in the following image.


Now, click on "OK" button.

Define IP address & Port

Choose one IP address from the list of available IP addresses and define the unique port number for the application, which will be unique within the defined IP address.

Choose Protocol & Host name (optional )

Choose the protocol for your application i.e HTTP or HTTPS which requires port 443 to be open and choose the Host name which will be used publicly to access the application. After defining all the configurations, the web site configuration window will look like this.


Now, click on OK button. It will create and add the application in IIS.

Browse the application using web browser

Browse the hosted application using your system (PC/Laptop) browser , Click on browse hyperlink which is highlighted in the following image

 

After clicking on preceding IIS shown image browse hyperlink, then application will open in your default web browser as shown in the following image
 
 

Preceding is our IIS hosted ASP.NET MVC application which is running in browser.

Note
  • This article is just guideline to show how to host ASP.NET MVC web API application on IIS .
  • Optimize the speed by setting debug as false etc., from web.config file as per your skills.
  • In this article, the optimization is not covered in depth.
  • Configure the authentication in IIS as per your requirement . 

Summary

I hope, this article is useful for all the readers to learn abouDeploy ASP.NET MVC Application on Local IIS. If you have any suggestions, please contact me.

Learn How to Create an ASP.NET MVC Application Step by Step

Insert Update Delete In Azure Cosmos DB SQL API Using ASP.NET Core API C#

In this article, I will explain the how to insert, read, update, and delete data from Azure Cosmos DB SQL API using ASP.NET Core API with C#. Let's learn step by step.

Azure Cosmos DB CRUD Flow By Vithal Wadje


Step 1: Set up Prerequisites

Set up the following one of the required pre-requisites to perform the CRUD operation in the Azure Cosmos DB

    • Azure Subscription OR
    • Azure Cosmos DB Emulator 

Azure Subscription 

To create the Azure cloud Cosmos DB account, you need an active Azure subscription. When you create the Cosmos DB account on the cloud, the Azure Cosmos DB Serverless account provides the first 1000 RU and 25 GB of storage for free per subscription.

Refer to the following link to learn the basics and how to create the Azure Cosmos DB account.

Azure Cosmos DB Emulator (offline)

As explained, the first approach requires an active Azure subscription as well as an active internet connection, which is not feasible for everyone who just wants to explore or learn about the Azure Cosmos DB.

To overcome the preceding issue, we can use the Azure Cosmos DB capabilities and features using the Azure Cosmos DB Emulator without an active Azure subscription or an active internet connection.

The Azure Cosmos DB Emulator currently does not have support for all the NoSQL APIs, but it will support the most commonly used NoSQL APIs, such as the SQL API and Mongo DB API, and in the future it may also support all the Cosmos DB APIs.

The following is the link to download the Azure Cosmos DB Emulator.

After clicking on the link, the official Microsoft documentation website gets opened, from which you can find and install the latest version of the Azure Cosmos DB Emulator.

Step 2: Create Azure Cosmos DB 

In this article, we are going to use the Azure Cosmos DB emulator instead of a Cloud Azure Cosmos DB account. If you are new to Azure Cosmos DB, please read the articles below to learn how to create an Azure Cosmos DB account. 
We are using the Azure Cosmos DB emulator in this article. search for the Azure Cosmos DB emulator from the search bar of the window once you download and install the emulator, which looks like the following:



The preceding image shows the Azure CosmosDB Account of the emulator, which will provide the same features as the Cloud Azure CosmosDB Account for development. Now click on the explorer and create the database and container. The explorer will then look like this:



We are storing the employee basic data in the Azure CosmosDB, and we are planning to use Department as a partition key and ID as the unique id for our employee records.

Note:
  • The ID and Department properties should be part of your backend input while inserting or updating the records; otherwise, you will get the exceptions.
I hope you have completed the required setup as explained in this article, including the creation of the Azure Cosmos account and database.

Step 3: Create ASP.NET Core web api Project

  1. Start then  All Programs and select "Microsoft Visual Studio".
  2. Once the Visual Studio Opens, Then click on Continue Without Code.
  3. Then Go to Visual Studio Menu, click on File => New Project then choose ASP.NET Core Web Api Project Template.
  4. Then define the project name, location of the project, then click on the next button.
  5. On the next screen, provide the additional details: framework, authentication type, and check the Enable Open API Support checkbox as shown below.


The preceding steps will create the ASP.NET Core Web API application and solution explorer. It will look like what is shown in the following image.



Step 4: Add Microsoft.Azure.Cosmos Nuget Package Reference

The Microsoft.Azure.Cosmos is the the latest nuget package to interact with the Azure cosmos DB. The Microsoft.Azure.Cosmos supports the basic to custom and complex database operations, follow the following steps to add the Nuget package.

  1. Right click on the Solution Explorer, find Manage NuGet Package Manager and click on it
  2. After as shown into the image and type in search box Microsoft.Azure.Cosmos
  3. Select Microsoft.Azure.Cosmos as shown into the image, 
  4. Choose version of Microsoft.Azure.Cosmos library and click on install button


I hope you have followed the same steps and installed the Microsoft.Azure.Cosmos nuget package.The next step is to delete the default controller and model class so we can start from scratch.


Step 5:Create the Model Class

  • First, delete the default model class, which is created outside the folder structure, so we can start from scratch. 
  • Next, create the folder named Model by right clicking on the solution explorer.
  • Create the model class Employee Model by right clicking on the Model folder, as shown in the following image


Now open the EmployeeModel.cs class file and add the following code.

EmployeeModel.cs

namespace EmployeeManagement.Model
{
    public class EmployeeModel
    {
        public string? id { get; set; }
        public string? Name { get; set; }
        public string? Country { get; set; }
        public string? City { get; set; }       
        public string? Department { get; set; }
        public string? Designation { get; set; }
        public DateTime? JoiningDate { get; set; }

    }
}

Step 6: Add the Controller

Create the Empty API Controller class EmployeeController by right clicking on the Controller folder as shown in the following image.



After adding the model class and API controller class, the solution explorer will look like the following:




Now open the EmployeeController.cs file and add the add the following configuration.
  • Define the following route at controller level, so that we can add the multiple Get, Post, Put, or Delete and avoid the name ambiguity exception.
    [ApiController]
    [Route("[api/[controller]/[action]]")]
    public class EmployeeController : ControllerBase
    {
    }

  • Declare the following variable and set the Azure Cosmos DB configuration by copying the details from step 2.
    [ApiController]
    [Route("api/[controller]/[action]")]
    public class EmployeeController : ControllerBase
    {
       
        // Cosmos DB details, In real use cases, these details should be configured in secure configuraion file.
        private readonly string CosmosDBAccountUri = "https://localhost:8081/";
        private readonly string CosmosDBAccountPrimaryKey = "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==";
        private readonly string CosmosDbName = "EmployeeManagementDB";
        private readonly string CosmosDbContainerName = "Employees";
}

Step 7: Create Method to Add Employee

Add the following code into the EmployeeController.cs class to Add the employees into the CosmosDB. This method takes input values using  the EmployeeModel class. 

        [HttpPost]
        public async Task<IActionResult> AddEmployee(EmployeeModel employee)
        {
            try
            {
                var container = ContainerClient();
                var response = await container.CreateItemAsync(employee, new PartitionKey(employee.Department));

                return Ok(response);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
               
        }


As explained in step 2, we are passing the ID and Department as a partition key as part of the employee input payload while adding the employee details. These parameters must be part of the input parameter payload.

Step 8:  Create Method to Get Employees

Add the following code into the EmployeeController.cs class to get all the employees from the Cosmos database.

        [HttpGet]
        public async Task<IActionResult> GetEmployeeDetails()
        {
            try
            {
                var container = ContainerClient();
                var sqlQuery = "SELECT * FROM c";
                QueryDefinition queryDefinition = new QueryDefinition(sqlQuery);
                FeedIterator<EmployeeModel> queryResultSetIterator = container.GetItemQueryIterator<EmployeeModel>(queryDefinition);


                List<EmployeeModel> employees = new List<EmployeeModel>();

                while (queryResultSetIterator.HasMoreResults)
                {
                    FeedResponse<EmployeeModel> currentResultSet = await queryResultSetIterator.ReadNextAsync();
                    foreach (EmployeeModel employee in currentResultSet)
                    {
                        employees.Add(employee);
                    }
                }

                return Ok(employees);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
           
        }


This example is not good practise since we are fetching all the employees without paging or a partition key filter, but we are doing this to learn how it works without making it complicated. In the next article, I will show how to get a list of records with the paging.

Step 9: Create Method to Get Employee by ID

Create the GetEmployeeDetailsById method in the EmployeeController.cs and add the following code to get the employee by employeeId and partition key from the Cosmos database.


        [HttpGet]
        public async Task<IActionResult> GetEmployeeDetailsById(string employeeId,string partitionKey)
        {

            try
            {
                var container = ContainerClient();
                ItemResponse<EmployeeModel> response = await container.ReadItemAsync<EmployeeModel>(employeeId, new PartitionKey(partitionKey));
                return Ok(response.Resource);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }

        }

Step 10: Create Method to Update Employee

Create the UpdateEmployee method in the EmployeeController.cs and add the following code to update  the employee by employeeId and partition key.

The CosmosDB does not support the partial update feature; rather, it actually replaces the existing item by getting the document to be updated and sending the same details to the database after fields to change or update.

       [HttpPut]
        public async Task<IActionResult> UpdateEmployee(EmployeeModel emp,string partitionKey)
        {

            try
            {

                var container = ContainerClient();
                ItemResponse<EmployeeModel> res = await container.ReadItemAsync<EmployeeModel>(emp.id, new PartitionKey(partitionKey));

                //Get Existing Item
                var existingItem = res.Resource;

                //Replace existing item values with new values 
                existingItem.Name = emp.Name;
                existingItem.Country = emp.Country;
                existingItem.City = emp.City;
                existingItem.Department = emp.Department;
                existingItem.Designation = emp.Designation;

              var updateRes=  await container.ReplaceItemAsync(existingItem, emp.id, new PartitionKey(partitionKey));

                return Ok(updateRes.Resource);

            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
          
        }

Step 11: Create Method to Delete Employee

Create the DeleteEmployee method in the EmployeeController.cs and add the following code to delete the employee by employeeId and partition key.

        [HttpDelete]
        public async Task<IActionResult> DeleteEmployee(string empId, string partitionKey)
        {

            try
            {

                var container = ContainerClient();
               var response= await container.DeleteItemAsync<EmployeeModel>(empId, new PartitionKey(partitionKey));
                return Ok(response.StatusCode);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
        }

    }

The entire code of the EmployeeController.cs class file will look like the following after adding all the methods together:

EmployeeController.cs

using EmployeeManagement.Model;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;

namespace EmployeeManagement.Controllers
{
    [ApiController]
    [Route("api/[controller]/[action]")]
    public class EmployeeController : ControllerBase
    {
       
        // Cosmos DB details, In real use cases, these details should be configured in secure configuraion file.
        private readonly string CosmosDBAccountUri = "https://localhost:8081/";
        private readonly string CosmosDBAccountPrimaryKey = "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==";
        private readonly string CosmosDbName = "EmployeeManagementDB";
        private readonly string CosmosDbContainerName = "Employees";


        /// <summary>
        /// Commom Container Client, you can also pass the configuration paramter dynamically.
        /// </summary>
        /// <returns> Container Client </returns>
        private  Container  ContainerClient()
        {

            CosmosClient cosmosDbClient = new CosmosClient(CosmosDBAccountUri, CosmosDBAccountPrimaryKey);
            Container containerClient = cosmosDbClient.GetContainer(CosmosDbName, CosmosDbContainerName);
            return containerClient;
           
        }


        [HttpPost]
        public async Task<IActionResult> AddEmployee(EmployeeModel employee)
        {
            try
            {
                var container = ContainerClient();
                var response = await container.CreateItemAsync(employee, new PartitionKey(employee.Department));

                return Ok(response);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
               
        }

        [HttpGet]
        public async Task<IActionResult> GetEmployeeDetails()
        {
            try
            {
                var container = ContainerClient();
                var sqlQuery = "SELECT * FROM c";
                QueryDefinition queryDefinition = new QueryDefinition(sqlQuery);
                FeedIterator<EmployeeModel> queryResultSetIterator = container.GetItemQueryIterator<EmployeeModel>(queryDefinition);


                List<EmployeeModel> employees = new List<EmployeeModel>();

                while (queryResultSetIterator.HasMoreResults)
                {
                    FeedResponse<EmployeeModel> currentResultSet = await queryResultSetIterator.ReadNextAsync();
                    foreach (EmployeeModel employee in currentResultSet)
                    {
                        employees.Add(employee);
                    }
                }

                return Ok(employees);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
           
        }
        [HttpGet]
        public async Task<IActionResult> GetEmployeeDetailsById(string employeeId,string partitionKey)
        {

            try
            {
                var container = ContainerClient();
                ItemResponse<EmployeeModel> response = await container.ReadItemAsync<EmployeeModel>(employeeId, new PartitionKey(partitionKey));
                return Ok(response.Resource);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }

        }
        [HttpPut]
        public async Task<IActionResult> UpdateEmployee(EmployeeModel emp,string partitionKey)
        {

            try
            {

                var container = ContainerClient();
                ItemResponse<EmployeeModel> res = await container.ReadItemAsync<EmployeeModel>(emp.id, new PartitionKey(partitionKey));

                //Get Existing Item
                var existingItem = res.Resource;

                //Replace existing item values with new values 
                existingItem.Name = emp.Name;
                existingItem.Country = emp.Country;
                existingItem.City = emp.City;
                existingItem.Department = emp.Department;
                existingItem.Designation = emp.Designation;

              var updateRes=  await container.ReplaceItemAsync(existingItem, emp.id, new PartitionKey(partitionKey));

                return Ok(updateRes.Resource);

            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
          
        }

        [HttpDelete]
        public async Task<IActionResult> DeleteEmployee(string empId, string partitionKey)
        {

            try
            {

                var container = ContainerClient();
               var response= await container.DeleteItemAsync<EmployeeModel>(empId, new PartitionKey(partitionKey));
                return Ok(response.StatusCode);
            }
            catch (Exception ex)
            {

                return BadRequest(ex.Message);
            }
        }

    }
}

Now, we have all the code and required configuration to work with Azure CosmosDB in our sample application.

Step 12: Run the ASP.NET Core API Application

Now press Keyboard F5 or the Visual Studio Run button to run the application. After running the application, the following screen will be shown in the browser with swagger UI having all the methods which we have created in our ASP.NET core web API, as shown in the following screenshot:


Now, we will test the functionality by using the Swagger UI, but you can use Postman or any other tool to execute the API endpoints.

Step 13: Azure Cosmos DB CRUD Demo 

Watch the following animated image to see how the insert, read, update, and delete operations of Azure Cosmos DB work.

Add Employees


Get List of Employees and Employee by Id




Update the Employee


Delete the Employee by Id




Summary

www.CodeNirvana.in

Protected by Copyscape
Copyright © Compilemode