Modern coding myths: web api

Ref: https://bitoftech.net/2022/08/25/deploy-microservice-application-azure-container-apps/

This articles gives co plete steps to deploy basic web api to Azure using Azure container apps and settting access to api either internal or external in docker config.

Other taks like creating UI as micro site and communication between components has been eplained very good and links given to github and other components . Articles gives complete picture of tasks to develop an basic microservice using azure container and dockers.

In this post, we will start by creating the solution skeleton by adding our first microservice named “Web API – Backend” as illustrated in the architecture diagram, then start provisioning Azure resources needed to deploy the service to Azure Container Apps using Azure CLI and Azure Portal.

As a prerequisite you need to have Visual Studio 2022 version 17.2 or higher, or VS Code to develop the solution, for my case I’ve started the Project using Visual Studio 2022 and then switched to VS code as debugging Dapr enabled applications and the extensions available in VS code makes developing the solution in VS code much easier. A recommendation is to use VS Code to build the solution, yet you can use Visual Studio 2022 and VS Code for local debugging.

The source code for this tutorial is available on GitHub. You can check the demo application too.

Setting up the Web API Backend Project

Step 1: Create the Web API Project

Create an empty solution and name it “TasksTracker.ContainerApps” then add a new ASP.NET Core Web API project named “TasksTracker.TasksManager.Backend.Api”, Configuration will be as the image below, check “Enable Docker” as we are going to containerize the application and deploy it to ACR, make sure “Linux” is selected for the Docker OS setting.

Step 2: Add Models (DTO)

Add a new folder named “Models” and create a new file named “TaskModel.cs” and paste the code below, those are the DTOs that will be used across the projects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
namespace TasksTracker.TasksManager.Backend.Api.Models
{
    public class TaskModel
    {
        public Guid TaskId { get; set; }
        public string TaskName { get; set; } = string.Empty;
        public string TaskCreatedBy { get; set; } = string.Empty;
        public DateTime TaskCreatedOn { get; set; }
        public DateTime TaskDueDate { get; set; }
        public string TaskAssignedTo { get; set; } = string.Empty;
        public bool IsCompleted { get; set; }
        public bool IsOverDue { get; set; }
 
    }
 
    public class TaskAddModel
    {
        public string TaskName { get; set; } = string.Empty;
        public string TaskCreatedBy { get; set; } = string.Empty;
        public DateTime TaskDueDate { get; set; }
        public string TaskAssignedTo { get; set; } = string.Empty;
    }
 
    public class TaskUpdateModel
    {
        public Guid TaskId { get; set; }
        public string TaskName { get; set; } = string.Empty;
        public DateTime TaskDueDate { get; set; }
        public string TaskAssignedTo { get; set; } = string.Empty;
    }
}

Step 3: Add In-memory Tasks Manager Service

We will work initially with data in memory to keep things simple with very limited dependency on any other components or data store and focus on the deployment of the backend API to Azure Container Apps, then we will switch this implementation with a concrete one where we are going to store data in Redis and Azure Cosmos DB using Dapr State Store building block, so to add the Fake Tasks Manager service (In-memory), create new folder named “Services” and add a new file named “ITasksManager.cs”, this will be the interface of Tasks Manager service. Paste the code below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
using TasksTracker.TasksManager.Backend.Api.Models;
 
namespace TasksTracker.TasksManager.Backend.Api.Services
{
    public interface ITasksManager
    {
        Task<List<TaskModel>> GetTasksByCreator(string createdBy);
 
        Task<TaskModel?> GetTaskById(Guid taskId);
 
        Task<Guid> CreateNewTask(string taskName, string createdBy, string assignedTo, DateTime dueDate);
 
        Task<bool> UpdateTask(Guid taskId, string taskName, string assignedTo, DateTime dueDate);
 
        Task<bool> MarkTaskCompleted(Guid taskId);
 
        Task<bool> DeleteTask(Guid taskId);
 
    }
}

Now add a new file named “FakeTasksManager.cs” and paste the code below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
using TasksTracker.TasksManager.Backend.Api.Models;
 
namespace TasksTracker.TasksManager.Backend.Api.Services
{
    public class FakeTasksManager : ITasksManager
    {
        private List<TaskModel> _tasksList = new List<TaskModel>();
        Random rnd = new Random();
 
        private void GenerateRandomTasks()
        {
            for (int i = 0; i < 10; i++)
            {
                var task = new TaskModel()
                {
                    TaskId = Guid.NewGuid(),
                    TaskName = $"Task number: {i}",
                    TaskCreatedBy = "tjoudeh@bitoftech.net",
                    TaskCreatedOn = DateTime.UtcNow.AddMinutes(i),
                    TaskDueDate = DateTime.UtcNow.AddDays(i),
                    TaskAssignedTo = $"assignee{rnd.Next(50)}@mail.com",
                };
 
                _tasksList.Add(task);
            }
        }
 
        public FakeTasksManager()
        {
            GenerateRandomTasks();
        }
 
        public Task<Guid> CreateNewTask(string taskName, string createdBy, string assignedTo, DateTime dueDate)
        {
            var task = new TaskModel()
            {
                TaskId = Guid.NewGuid(),
                TaskName = taskName,
                TaskCreatedBy = createdBy,
                TaskCreatedOn = DateTime.UtcNow,
                TaskDueDate = dueDate,
                TaskAssignedTo = assignedTo,
            };
 
            _tasksList.Add(task);
            return Task.FromResult(task.TaskId);
        }
 
        public Task<bool> DeleteTask(Guid taskId)
        {
            var task = _tasksList.FirstOrDefault(t => t.TaskId.Equals(taskId));
 
            if (task != null)
            {
                _tasksList.Remove(task);
                return Task.FromResult(true);
            }
 
            return Task.FromResult(false);
        }
 
        public Task<TaskModel?> GetTaskById(Guid taskId)
        {
            var taskModel = _tasksList.FirstOrDefault(t => t.TaskId.Equals(taskId));
 
            return Task.FromResult(taskModel);
        }
 
        public Task<List<TaskModel>> GetTasksByCreator(string createdBy)
        {
            var tasksList = _tasksList.Where(t => t.TaskCreatedBy.Equals(createdBy)).OrderByDescending(o => o.TaskCreatedOn).ToList();
 
            return Task.FromResult(tasksList);
        }
 
        public Task<bool> MarkTaskCompleted(Guid taskId)
        {
            var task = _tasksList.FirstOrDefault(t => t.TaskId.Equals(taskId));
 
            if (task != null)
            {
                task.IsCompleted = true;
                 return Task.FromResult(true);
            }
 
             return Task.FromResult(false);
        }
 
        public Task<bool> UpdateTask(Guid taskId, string taskName, string assignedTo, DateTime dueDate)
        {
            var task = _tasksList.FirstOrDefault(t => t.TaskId.Equals(taskId));
 
            if (task != null)
            {
                task.TaskName = taskName;
                task.TaskAssignedTo = assignedTo;
                task.TaskDueDate = dueDate;
                return Task.FromResult(true);
            }
 
             return Task.FromResult(false);
        }
    }
}

The code above is self-explanatory, it generates 10 tasks and stores them in a list in memory, as well it has some operations to add/remove/update those tasks.

Step 4: Register FakeTasksManager on project startup

Open file “Program.cs” and register the newly created service by adding the line highlighted below

1
2
3
4
5
6
7
8
9
10
11
using TasksTracker.TasksManager.Backend.Api.Services;
 
var builder = WebApplication.CreateBuilder(args);
 
// Add services to the container.
 
builder.Services.AddSingleton<ITasksManager, FakeTasksManager>();
 
// Code removed for brevity
 
app.Run();

Step 5: Create API endpoints to manage tasks

Now we will add a new controller named “TasksController.cs” under the folder “Controllers” which will contain simple action methods to enable basic CRUD operations on tasks.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
namespace TasksTracker.TasksManager.Backend.Api.Controllers
{
    [Route("api/tasks")]
    [ApiController]
    public class TasksController : ControllerBase
    {
        private readonly ILogger<TasksController> _logger;
        private readonly ITasksManager _tasksManager;
 
        public TasksController(ILogger<TasksController> logger, ITasksManager tasksManager)
        {
            _logger = logger;
            _tasksManager = tasksManager;
        }
 
        [HttpGet]
        public async Task<IEnumerable<TaskModel>> Get(string createdBy)
        {
            return await _tasksManager.GetTasksByCreator(createdBy);
        }
 
        [HttpGet("{taskId}")]
        public async Task<IActionResult> GetTask(Guid taskId)
        {
            var task = await _tasksManager.GetTaskById(taskId);
            if (task != null)
            {
                return Ok(task);
            }
 
            return NotFound();
 
        }
 
        [HttpPost]
        public async Task<IActionResult> Post([FromBody] TaskAddModel taskAddModel)
        {
            var taskId = await _tasksManager.CreateNewTask(taskAddModel.TaskName,
                                taskAddModel.TaskCreatedBy,
                                taskAddModel.TaskAssignedTo,
                                taskAddModel.TaskDueDate);
 
        
            return Created($"/api/tasks/{taskId}", null);
 
        }
 
        [HttpPut("{taskId}")]
        public async Task<IActionResult> Put(Guid taskId, [FromBody] TaskUpdateModel taskUpdateModel)
        {
            var updated = await _tasksManager.UpdateTask(taskId,
                                                    taskUpdateModel.TaskName,
                                                    taskUpdateModel.TaskAssignedTo,
                                                    taskUpdateModel.TaskDueDate);
            if (updated)
            {
                return Ok();
            }
 
            return BadRequest();
        }
 
        [HttpPut("{taskId}/markcomplete")]
        public async Task<IActionResult> MarkComplete(Guid taskId)
        {
            var updated = await _tasksManager.MarkTaskCompleted(taskId);
 
            if (updated)
            {
                return Ok();
            }
 
            return BadRequest();
        }
 
        [HttpDelete("{taskId}")]
        public async Task<IActionResult> Delete(Guid taskId)
        {
            var deleted = await _tasksManager.DeleteTask(taskId);
            if (deleted)
            {
                return Ok();
            }
 
            return NotFound();
        }
    }
}

Step 6: Add Dockerfile to the Web API project

In case you didn’t check the “Enable Docker” checkbox when creating the project we need to add a Dockerfile to the Web API project, so ensure you are on the root of the project and add file named “Docekrfile” and paste the code below:

Notes:

If you are using Visual Studio 2022, you can right-click on the Web API project and then select “Add->Docker Support”, it will generate the same file for you.
If you want to run the project locally on Docker, you need to install Docker Desktop, it is straight forward installation and can be installed from here. My recommendation is to have Docker Desktop installed as we are going to need it when introducing Dapr state Management API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443
 
FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["TasksTracker.TasksManager.Backend.Api/TasksTracker.TasksManager.Backend.Api.csproj", "TasksTracker.TasksManager.Backend.Api/"]
RUN dotnet restore "TasksTracker.TasksManager.Backend.Api/TasksTracker.TasksManager.Backend.Api.csproj"
COPY . .
WORKDIR "/src/TasksTracker.TasksManager.Backend.Api"
RUN dotnet build "TasksTracker.TasksManager.Backend.Api.csproj" -c Release -o /app/build
 
FROM build AS publish
RUN dotnet publish "TasksTracker.TasksManager.Backend.Api.csproj" -c Release -o /app/publish
 
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "TasksTracker.TasksManager.Backend.Api.dll"]

Now you can run your application locally to test, try to issue GET request to the endpoint https://localhost:7088/api/tasks?createdby=tjoudeh@bitoftech.net and you should receive an array of tasks similar to the below:

1
2
3
4
5
6
7
8
9
10
11
12
[
  {
	"taskId": "2d975e03-1f0a-47db-bb45-1ce5896b747d",
	"taskName": "Task number: 9",
	"taskCreatedBy": "tjoudeh@bitoftech.net",
	"taskCreatedOn": "2022-08-22T22:07:12.3818927Z",
	"taskDueDate": "2022-08-31T21:58:12.3818928Z",
	"taskAssignedTo": "assignee41@mail.com",
	"isCompleted": false,
	"isOverDue": false
  }
]

Deploy the Web API Backend Project to Azure Container Apps

There are several ways to deploy the Web API to Azure Container Apps, this is a good link to view different ways, for this tutorial we will use Azure CLI/PowerShell.

Step 1: Install/Upgrade Azure Container Apps Extension

Open the PowerShell console on your machine, and sign in to Azure from the CLI. Run the below command, and follow the prompts to complete the authentication process.

1
az login

If you have multiple Azure subscriptions under the account you authenticated with you need to select the subscription you want to provision resources under

1
az account set --subscription <name or id>

Ensure you’re running the latest version of the CLI via the upgrade command.

1
az upgrade

Now install or update the Azure Container Apps extension for the CLI.

1
az extension add --name containerapp --upgrade

Register the “Microsoft.App” and “Microsoft.OperationalInsights” namespaces if you haven’t already registered them in your Azure subscription.

1
2
az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

Step 2: Provision Azure Resources

Now we will be defining some variables in the PowerShell console to use them across the series of posts, you should change the values of those variables to be able to create the resources successfully, some of those variables should be unique across all Azure subscriptions such as Azure Container Registry name.

1
2
3
4
5
$RESOURCE_GROUP="tasks-tracker-rg"
$LOCATION="eastus"
$ENVIRONMENT="tasks-tracker-containerapps-env"
$BACKEND_API_NAME="tasksmanager-backend-api"
$ACR_NAME="taskstrackeracr"

Now we will create a resource group to organize the services related to our application

1
2
3
az group create `
  --name $RESOURCE_GROUP `
  --location "$LOCATION"

Next, we will create an Azure Container Registry (ACR) instance in the resource group to store images of all Microservices we are going to build during this tutorial, make sure that you set the admin-enabled flag to true in order to seamlessly authenticate Azure container app when trying to create the container app using the image stored in ACR

1
2
3
4
5
az acr create `
  --resource-group $RESOURCE_GROUP `
  --name $ACR_NAME `
  --sku Basic `
  --admin-enabled true

Now we will build the Web API project on ACR and push the docker image to ACR. Use the below command to initiate the image build and push process using ACR. The “.” at the end of the command represents the docker build context, in our case, we need to be on the parent directory which hosts the .csproject.

1
2
cd {YourLocalPath}\TasksTracker.ContainerApps
az acr build --registry $ACR_NAME --image "tasksmanager/$BACKEND_API_NAME" --file 'TasksTracker.TasksManager.Backend.Api/Dockerfile' .

Once this step is completed you can verify the results by going to the Azure portal and check that a new repository named “tasksmanager/tasksmanager-backend-api” has been created and there is a new docker image with a “latest” tag is created, it should look like the below

Step 3: Provision Azure Container Env and Container App

Next is to create Azure Container Apps Environment, as shared previously, it acts as a secure boundary around a group of all container apps we are going to provision during this tutorial, to create it, run the below command:

1
2
3
4
az containerapp env create `
  --name $ENVIRONMENT `
  --resource-group $RESOURCE_GROUP `
  --location $LOCATION

Note: If you are using the CLI command to create Container Apps Environment, it is better to set the property “–dapr-instrumentation-key” when creating the Environment, so you need to provision Application Insights resource to get its instrumentation key, more details on this post.

The last step here is to create and deploy the Web API to Azure Container App following the below command:

1
2
3
4
5
6
7
8
9
10
11
12
az containerapp create `
  --name $BACKEND_API_NAME  `
  --resource-group $RESOURCE_GROUP `
  --environment $ENVIRONMENT `
  --image "$ACR_NAME.azurecr.io/tasksmanager/$BACKEND_API_NAME" `
  --registry-server "$ACR_NAME.azurecr.io" `
  --target-port 80 `
  --ingress 'external' `
  --min-replicas 1 `
  --max-replicas 2 `
  --cpu 0.25 --memory 0.5Gi `
  --query configuration.ingress.fqdn

Some notes on the above command:

Ingress param is set to “external” which means that this container app (Web API) project will be accessible from the public internet. When Ingress is set to “Internal” or “External” it will be assigned a fully qualified domain name (FQDN). Important notes about IP addresses and domain names can be found here.
The target port param is set to 80, this is the port our Web API container listens to for incoming requests.
We didn’t specify the ACR registry username and password, “az containerapp create” command was able to look up ACR username and password and add them as a secret under the created Azure container app for future container updates.
The minimum and the maximum number of replicas are set, more about this when we talk about Autoscaling. In the meantime, only 1 single instance of this container app will be provisioned as Auto scale is not configured.
We are setting the size of the Container App, the total amount of CPUs and memory requested for the container app must add up to certain combinations, for full details check the link here
The “query” property will filter the response coming from the command and just return the FQDN.

For full details on all available parameters for this command, please visit this page.

Step 4: Verify the deployment of the Azure Container App.

Now we can navigate to the Azure Portal and select the resource group named “tasks-tracker-rg” created, you should see the 4 recourses created below. By default when you create an Azure Container Environment, a Log Analytics workspace will be created, we will cover this in the Monitoring and observability post.

Now copy the FQDN (Application URL) of the Azure container app named “tasksmanager-backend-api” and issue GET request similar to this one: https://tasksmanager-backend-api.agreeablestone-8c14c04c.eastus.azurecontainerapps.io/api/tasks/?createdby=tjoudeh@bitoftech.net
And you should receive an array of the 10 tasks similar to the below image

In the next post, we will see how we will add a new Frontend Web App as a microservice and how it will communicate with the backend API.

Modern coding myths

Wednesday, November 1, 2023

Deploy backend API Microservice to Azure Container Apps