When building HTTP APIs, it can be tempting to synchronously run long-running tasks in a request handler. This approach can lead to slow responses, timeouts, and resource exhaustion. If a request times out or a connection is dropped, the client won’t know if the operation completed or not. For CPU-bound tasks, this approach can also bog down the server, making it unresponsive to other requests.

In this post, we’ll look at how to build an asynchronous HTTP API with Azure Container Apps. We’ll create a simple API that implements the Asynchronous Request-Reply pattern: with the API hosted in a container app and the asynchronous processing done in a job. This approach provides a much more robust and scalable solution for long-running tasks.

Long-running API requests in Azure Container Apps

Azure Container Apps is a serverless container platform. It’s ideal for hosting a variety of workloads, including HTTP APIs.

Like other serverless and PaaS platforms, Azure Container Apps is designed for short-lived requests — its ingress currently has a maximum timeout of 4 minutes. As an autoscaling platform, it’s designed to scale dynamically based on the number of incoming requests. When scaling in, replicas are removed. Long-running requests can terminate abruptly if the replica handling the request is removed.

Azure Container Apps jobs

Azure Container Apps has two types of resources: apps and jobs. Apps are long-running services that respond to HTTP requests or events. Jobs are tasks that run to completion and can be triggered by a schedule or an event.

Jobs can also be triggered programmatically. This makes them a good fit for implementing asynchronous processing in an HTTP API. The API can start a job execution to process the request and return a response immediately. The job can then take as long as it needs to complete the processing. The client can poll a status endpoint on the app to check if the job has completed and get the result.

The Asynchronous Request-Reply pattern

Asynchronous Request-Reply is a common pattern for handling long-running operations in HTTP APIs. Instead of waiting for the operation to complete, the API returns a status code indicating that the operation has started. The client can then poll the API to check if the operation has completed.

Here’s how the pattern applies to Azure Container Apps:

The client sends a request to the API (hosted as a container app) to start the operation.
The API saves the request (our example uses Azure Cosmos DB), starts a job to process the operation, and returns a 202 Accepted status code with a Location header pointing to a status endpoint.
The client polls the status endpoint. While the operation is in progress, the status endpoint returns a 200 OK status code with a Retry-After header indicating when the client should poll again.
When the operation is complete, the status endpoint returns a 303 See Other status code with a Location header pointing to the result. The client automatically follows the redirect to get the result.

Async HTTP API app

You can find the source code in this GitHub repository.

The API is a simple Node.js app that uses Fastify. It demonstrates how to build an async HTTP API that accepts orders and offloads the processing of the orders to jobs. The app has a few simple endpoints.

POST /orders

This endpoint accepts an order in its body. It saves the order to Cosmos DB with a status of “pending” and starts a job execution to process the order.

fastify.post(‘/orders’, async (request, reply) => {
const orderId = randomUUID()

// save order to Cosmos DB
await container.items.create({
id: orderId,
status: ‘pending’,
order: request.body,
})

// start job execution
await startProcessorJobExecution(orderId)

// return 202 Accepted with Location header
reply.code(202).header(‘Location’, ‘/orders/status/’ + orderId).send()
})

We’ll take a look at the job later in this article. In the above code snippet, startProcessorJobExecution is a function that starts the job execution. It uses the Azure Container Apps management SDK to start the job.

const credential = new DefaultAzureCredential()
const containerAppsClient = new ContainerAppsAPIClient(credential, subscriptionId)

// …

async function startProcessorJobExecution(orderId) {
// get the existing job’s template
const { template: processorJobTemplate } =
await containerAppsClient.jobs.get(resourceGroupName, processorJobName)

// add the order ID to the job’s environment variables
const environmentVariables = processorJobTemplate.containers[0].env
environmentVariables.push({ name: ‘ORDER_ID’, value: orderId })
const jobStartTemplate = { template: processorJobTemplate }

// start the job execution with the modified template
const jobExecution = await containerAppsClient.jobs.beginStartAndWait(
resourceGroupName, processorJobName, {
template: processorJobTemplate,
}
)
}

The job takes the order ID as an environment variable. To set the environment variable, we start the job execution with a modified template that includes the order ID.

We use managed identities to authenticate with both the Azure Container Apps management SDK and the Cosmos DB SDK.

GET /orders/status/:orderId

The previous endpoint returns a 202 Accepted status code with a Location header pointing to this status endpoint. The client can poll this endpoint to check the status of the order.

This request handler retrieves the order from Cosmos DB. If the order is still pending, it returns a 200 OK status code with a Retry-After header indicating when the client should poll again. If the order is complete, it returns a 303 See Other status code with a Location header pointing to the result.

fastify.get(‘/orders/status/:orderId’, async (request, reply) => {
const { orderId } = request.params

// get the order from Cosmos DB
const { resource: item } = await container.item(orderId, orderId).read()

if (item === undefined) {
reply.code(404).send()
return
}

if (item.status === ‘pending’) {
reply.code(200).headers({
‘Retry-After’: 10,
}).send({ status: item.status })
} else {
reply.code(303).header(‘Location’, ‘/orders/’ + orderId).send()
}
})

GET /orders/:orderId

This endpoint returns the result of the order processing. The status endpoint redirects to this resource when the order is complete. It retrieves the order from Cosmos DB and returns it.

fastify.get(‘/orders/:orderId’, async (request, reply) => {
const { orderId } = request.params

// get the order from Cosmos DB
const { resource: item } = await container.item(orderId, orderId).read()

if (item === undefined || item.status === ‘pending’) {
reply.code(404).send()
return
}

if (item.status === ‘completed’) {
reply.code(200).send({ id: item.id, status: item.status, order: item.order })
} else if (item.status === ‘failed’) {
reply.code(500).send({ id: item.id, status: item.status, error: item.error })
}
})

Order processor job

The order processor job is a another Node.js app. As it’s just a demo, it just waits a while, updates the order status in Cosmos DB, and exits. In a real-world scenario, the job would process the order, update the order status, and possibly send a notification.

We deploy it as a job in Azure Container Apps. The POST /orders endpoint above starts the job execution. The job takes the order ID as an environment variable and uses it to update the order status in Cosmos DB.

Like the API app, the job uses managed identities to authenticate with Azure Cosmos DB.

The code is in the same GitHub repository.

import { DefaultAzureCredential } from ‘@azure/identity’
import { CosmosClient } from ‘@azure/cosmos’

const credential = new DefaultAzureCredential()
const client = new CosmosClient({
endpoint: process.env.COSMOSDB_ENDPOINT,
aadCredentials: credential
})

const database = client.database(‘async-api’)
const container = database.container(‘statuses’)

const orderId = process.env.ORDER_ID

const orderItem = await container.item(orderId, orderId).read()
const orderResource = orderItem.resource

if (orderResource === undefined) {
console.error(‘Order not found’)
process.exit(1)
}

// simulate processing time
const orderProcessingTime = Math.floor(Math.random() * 30000)
console.log(`Processing order ${orderId} for ${orderProcessingTime}ms`)
await new Promise(resolve => setTimeout(resolve, orderProcessingTime))

// update order status in Cosmos DB
orderResource.status = ‘completed’
orderResource.order.completedAt = new Date().toISOString()
await orderItem.item.replace(orderResource)
console.log(`Order ${orderId} processed`)

HTTP client

To call the API and wait for the result, here’s a simple JavaScript function that works just like fetch but waits for the job to complete. It also accepts a callback function that’s called each time the status endpoint is polled so you can log the status or update the UI.

async function fetchAndWait() {
const input = arguments[0]
let init = arguments[1]
let onStatusPoll = arguments[2]
// if arguments[1] is not a function
if (typeof init === ‘function’) {
init = undefined
onStatusPoll = arguments[1]
}
onStatusPoll = onStatusPoll || (async () => {})

// make the initial request
const response = await fetch(input, init)

if (response.status !== 202) {
throw new Error(`Something went wrongnResponse: ${await response.text()}n`)
}

const responseOrigin = new URL(response.url).origin
let statusLocation = response.headers.get(‘Location’)
// if the Location header is not an absolute URL, construct it
statusLocation = new URL(statusLocation, responseOrigin).href

// poll the status endpoint until it’s redirected to the final result
while (true) {
const response = await fetch(statusLocation, {
redirect: ‘follow’
})

if (response.status !== 200 && !response.redirected) {
const data = await response.json()
throw new Error(`Something went wrongnResponse: ${JSON.stringify(data, null, 2)}n`)
}

// redirected, return final result and stop polling
if (response.redirected) {
const data = await response.json()
return data
}

// the Retry-After header indicates how long to wait before polling again
const retryAfter = parseInt(response.headers.get(‘Retry-After’)) || 10

// call the onStatusPoll callback so we can log the status or update the UI
await onStatusPoll({
response,
retryAfter,
})

await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
}
}

To use the function, we call it just like fetch. We pass an additional argument that’s a callback function that’s invoked each time the status endpoint is polled.

const order = await fetchAndWait(‘/orders’, {
method: ‘POST’,
headers: {
‘Content-Type’: ‘application/json’
},
body: JSON.stringify({
“customer”: “Contoso”,
“items”: [
{
“name”: “Apple”,
“quantity”: 5
},
{
“name”: “Banana”,
“quantity”: 3
},
],
})
}, async ({ response, retryAfter }) => {
const { status } = await response.json()
const requestUrl = response.url
messagesDiv.innerHTML += `Order status: ${status}; retrying in ${retryAfter} seconds (${requestUrl})n`
})

// display the final result
document.querySelector(‘#order’).innerHTML = JSON.stringify(order, null, 2)

If we run this in the browser, we can open up dev tools and see all the HTTP requests that are made.

In the portal, we also can see the job execution history.

Conclusion

With the Asynchronous Request-Reply pattern, we can build robust and scalable HTTP APIs that handle long-running operations. By using Azure Container Apps jobs, we can offload the processing to a job execution that doesn’t consume resources from the API app. This robust approach allows the API to respond quickly and handle many requests concurrently.

Originally posted on anthonychu.ca

​Microsoft Tech Community – Latest Blogs –Read More 

In the ever-evolving landscape of cloud application development, managing configurations, ensuring resilience, and maintaining seamless integration between various components can be quite challenging.

This is where .NET Aspire comes into play! A robust application development framework designed to simplify these complexities, allowing developers to focus on creating features rather than dealing with extensive configurations.

In this article, we will explore the core aspects of .NET Aspire, examining its benefits, the configuration process, and integration with JavaScript, as presented in an outstanding session at the recent .NET Aspire Developers Day by Chris Noring, Senior Developer Advocate at Microsoft.

.NET Aspire Developers Day

The latest .NET Aspire Developers Day, which took place on July 23, 2024, was a great event with lots of technical and practical sessions, featuring different programming languages and frameworks. The main goal of this online event was to show how easy it is to develop modern applications with the power of .NET Aspire!

No worries if you missed the event! Here’s the link to the recording so you can check out and learn more about .NET Aspire and how it can help you in different software development situations.

.NET Aspire Developers Day Online Event

So, what exactly is .NET Aspire? Let’s dive in and find out more!

Understanding .NET Aspire

.NET Aspire is a cloud-ready framework that helps you build distributed and production-ready applications. It’s got NuGet packages that make it easier to build apps that are made up of small, connected services, which are called microservices.

Purpose of .NET Aspire

.NET Aspire is all about making the development process easier, especially when it comes to building cloud-based apps. It’s got tools and patterns that make everything easier, from getting set up to running distributed applications. And also, .NET Aspire makes orchestration simple. It automatically connects projects and their dependencies, so you don’t have to worry about the technical details.

Simplified Orchestration

Orchestration in .NET Aspire is all about making your local development environment easier to use by automating the configuration and interconnection of multiple projects and their dependencies. It’s not meant to replace the kind of robust systems you’d use in production, like Kubernetes. What .NET Aspire does is provide abstractions that make it easier to set up services, find them, and configure containers.

Ready-to-Use Components

.NET Aspire also comes with ready-to-use components like Redis or PostgreSQL that you can add to your project with just a few lines of code. Plus, it’s got project templates and tools for Visual Studio, Visual Studio Code, and the .NET CLI, so it’s a breeze to create and manage your projects.

Usage Example

For instance, you can add a Redis container with just a few lines of code and set up the connection string automatically in the Frontend project.

var builder = DistributedApplication.CreateBuilder(args);
var cache = builder.AddRedis(“cache”);
builder.AddProject<Projects.MyFrontend>(“frontend”)
.WithReference(cache);

If you want to learn more about .NET Aspire, I suggest checking out the official documentation. It’s got all the details and examples you need to get started developing with .NET Aspire.

Access the official .NET Aspire documentation now: Official .NET Aspire Documentation

Getting Started with .NET Aspire with JavaScript

At the .NET Aspire Developers Day session, Chris Noring showed us an amazing integration between .NET Aspire and JavaScript. He demonstrated how we can use the power of .NET Aspire and the flexibility of JavaScript to create modern, distributed applications.

If you would like to watch Chris Noring’s full session, just click on the link below:

He started off by showing us how simple it is to get started with .NET Aspire. All you need to do is install a few things:

.NET 8
.NET Aspire Workload
OCI-Compatible with Docker ou Podman
Visual Studio Code ou Visual Studio
C# Dev Kit Extension

It’s really straightforward to set up a .NET Aspire project. You can use Visual Studio, Visual Studio Code, or just the terminal.

For instance, you can create a new project using the terminal with this command:

dotnet new aspire-starter

This command puts together a project structure that includes the main bits and pieces you need, like AppHost (the brains of the operation), ServiceDefaults, and a starter application.

Once you have got the project structured, the next thing to do is to run it. Before you get started, you’ll need to make sure that HTTPS is enabled, because .NET Aspire needs HTTPS to work.

To get HTTPS up and running, you can use this command:

dotnet dev-certs https –trust

To get the project up and running, just use the command:

dotnet run

When you run the AppHost project, you’ll see a dashboard with all the resources in your project, like APIs and Frontend services. This dashboard gives you a great overview of your application’s metrics, logs, and active requests, making it easier to monitor and debug your cloud application.

Chris Noring showed us all this at his session at .NET Aspire Developers Day. He made it look really easy and practical to start developing modern applications with .NET Aspire.

If you like, I recommend reading the tutorial: “Quickstart: Build your first .NET Aspire project” available in the official .NET Aspire documentation.

More on Orchestration with .NET Aspire

Let’s take a closer look at what Chris Noring shared in this part of the session.

Orchestrating distributed applications with .NET Aspire is all about setting up and linking the different parts that make up the application. The aspire-manifest.json file is key to this process. It shows how the services connect and configure within the application.

This automation makes life easier for developers, so they don’t have to manually configure each connection and dependency.

The Role of aspire-manifest.json

The aspire-manifest.json is a JSON file that’s automatically generated by .NET Aspire. It contains all the necessary info about the app’s resources and components.

It’s got all the details you need, like connection strings, environment variables, ports, and communication protocols. This manifest makes sure all the app’s services connect right and work together smoothly.

Let’s take a look at the example Chris Noring showed us in the session on how to configure a Redis cache and a Node.js Product API using the Program.cs file.

var cache = builder.AddRedis(“cache”);

var productApi = builder.AddNpmApp(“productapi”, “../NodeApi”, “watch”)
.WithReference(cache)
.WithHttpEndpoint(env: “PORT”)
.WithExternalHttpEndpoints()
.PublishAsDockerFile();

In this example, Redis is configured as a cache service, and the product API, developed in Node.js, is configured to use this cache. The WithReference(cache) method ensures that the product API can connect to Redis. The PublishAsDockerFile() method creates a Dockerfile for the application, allowing it to run in a container.

How Does the Manifest Reflect These Configurations?

Once you have run the code, .NET Aspire will create an aspire-manifest.json file that shows all the settings you’ve configured in the code. Chris goes over how the manifest shows the Redis and Product API configuration:

{
“productapi”: {
“type”: “dockerfile.v0”,
“path”: “../NodeApi/Dockerfile”,
“context”: “../NodeApi”,
“env”: {
“NODE_ENV”: “development”,
“ConnectionStrings__cache”: “{cache.connectionString}”,
“PORT”: “{productapi.bindings.http.port}”
},
“bindings”: {
“http”: {
“scheme”: “http”,
“protocol”: “tcp”,
“transport”: “http”,
“targetPort”: 8000,
“external”: true
}
}
}
}

In this part of the manifest, we can see that the Product API (productapi) is set up to use the Redis connection string (ConnectionStrings__cache), which is automatically generated and added to the application’s environment. On top of that, the manifest says that the Product API will be available via HTTP on port 8000.

How to Create or Update the Manifest?

If you want to generate or update the aspire-manifest.json file, you can use this command:

dotnet run –publisher manifest –output-path aspire-manifest.json

This command runs the application and generates the manifest, which is essential for deployment in production environments or testing during development.

Integrating JavaScript with .NET Aspire

.NET Aspire is flexible enough to work with JavaScript, so you can use it for both front-end and back-end development. This lets developers use popular JavaScript frameworks and libraries with .NET components, creating one unified development environment.

Front-End Example with Angular

Chris Noring showed us how to integrate .NET Aspire into a front-end project developed in Angular. You can make backend configuration and API connection easier by using environment variables. These are automatically generated and injected into the project.

Backend Configuration in Angular

The proxy.conf.js file is used to redirect API calls in the development environment to the right backend. The backend URLs, which can be different in each environment, are managed using environment variables. Here’s an example of how it’s set up:

module.exports = {
“/api”: {
target: process.env[“services__weatherapi__https__0”] || process.env[“services__weatherapi__http__0”],
secure: process.env[“NODE_ENV”] !== “development”,
pathRewrite: { “^/api”: “” },
},
};

In this example, we are setting the target based on the environment variables services__weatherapi__https__0 or services__weatherapi__http__0, which are automatically injected by .NET Aspire. This configuration makes sure that the Angular front end can connect to the backend service no matter what environment it’s in (development, test, or production).

Using HttpClient in Angular

In Angular, you can interact with the backend using the HttpClient service, as shown in the following example:

constructor(private http: HttpClient) {
this.http.get<WeatherForecast[]>(‘api/weatherforecast’).subscribe({
next: result => this.forecasts = result,
error: console.error
});
}

This snippet shows how the call to the api/weatherforecast API is automatically redirected to the correct backend, thanks to the configuration made in proxy.conf.js. This makes it easier for the Angular frontend and the backend to communicate, and it makes sure that the environment variables set up in the .NET Aspire manifest are used correctly.

Integration with Node.js and .NET Aspire

.NET Aspire makes it easy to manage .NET apps and also lets you easily add other technologies like Node.js. This flexibility lets you build distributed apps that combine different tech stacks in a really efficient way.

Orchestration in AppHost

In the orchestration performed in AppHost, .NET Aspire makes it easy for you to connect different components of your application, such as a Node.js Frontend and a Backend API.

In the second image, you can see how AppHost is configured in the code.

var cache = builder.AddRedis(“cache”);

var weatherapi = builder.AddProject<Projects.AspireWithNode_AspNetCoreApi>(“weatherapi”);

var frontend = builder.AddNpmApp(“frontend”, “../NodeFrontend”, “watch”)
.WithReference(weatherapi)
.WithReference(cache)
.WithHttpEndpoint(env: “PORT”)
.WithExternalHttpEndpoints()
.PublishAsDockerFile()

In this example, we’ve got Redis as the cache, the weatherapi for the weather forecast API, and the frontend is the Node.js application. The WithReference() function links everything together, so the frontend can access both Redis and the API.

Using PublishAsDockerFile() lets you package the frontend as a Docker container, which makes it easy to deploy in any environment.

In the Node.js Application…

In the example shown in the images, the Node.js app is set up to get the cache address and API URL straight from the Aspire project.

This is done through environment variables that are automatically generated based on the resources defined in the .NET Aspire manifest.

const cacheAddress = env[‘ConnectionStrings__cache’];
const apiServer = env[‘services__weatherapi__https__0’] ?? env[‘services__weatherapi__http__0’];

.NET Aspire automatically injects environment variables like ConnectionStrings__cache and services__weatherapi into the Node.js application’s runtime environment. These variables have the info needed for the app to connect to Redis and the weather forecast API correctly.

With this info, the app can easily access the cache and the API without having to hard-code URLs or connection strings. This makes it easier to maintain the code and also makes sure the application works correctly in different environments (development, test, production).

Example of Usage in an Express Route

Here’s an example of how this configuration is used in an Express route in a Node.js application:

app.get(‘/’, async (req, res) => {
let cachedForecasts = await cache.get(‘forecasts’);
if (cachedForecasts) {
res.render(‘index’, { forecasts: JSON.parse(cachedForecasts) });
return;
}

let response = await fetch(`${apiServer}/weatherforecast`);
let forecasts = await response.json();
await cache.set(‘forecasts’, JSON.stringify(forecasts));
res.render(‘index’, { forecasts });
});

The app first checks the Redis cache for weather forecasts. If the data is in the cache, it’s displayed right away. Otherwise, the app makes a request to the weather forecast API (apiServer), stores the results in the cache, and then displays them.

This logic really speeds up the app and makes it more efficient, so data is retrieved from the cache as quickly as possible.

Wrapping Up

.NET Aspire is a great tool for building modern apps, especially those that use cloud-based, distributed systems. It gets rid of a lot of the complexity that comes with orchestration, service discovery, and environment configuration, so developers can focus more on writing business logic and less on managing infrastructure.

It’s also great that it works seamlessly with JavaScript and Node.js. This makes it a really useful tool for building robust, scalable apps that can work across different tech stacks.

If you’re looking to make your development workflow easier while making sure your apps are ready for the real world, .NET Aspire is worth checking out.

Don’t miss the opportunity to dive deeper into .NET Aspire’s capabilities. Watch the full session by Chris Noring at .NET Aspire Developers Day to see these concepts in action and learn more about how you can leverage this powerful framework in your projects.

Additional Resources

If you’re looking to keep learning and getting more proficient in .NET Aspire, here are some additional resources to help you out:

Documentação Oficial – .NET Aspire
Orchestrate Node.js apps in .NET Aspire
Code Sample: .NET Aspire with Angular, React, and Vue
Code Sample: .NET Aspire + Node.js
Curso Grátis: Criar aplicativos distribuídos com o .NET Aspire
Video series: Welcome to .NET Aspire

I hope this article has been helpful and inspiring for you. If you have any questions or suggestions, please feel free to share them in the comments below. I’m here to help and support you as you learn and grow professionally.

Until next time! Keep learning, creating, and sharing! 

​Microsoft Tech Community – Latest Blogs –Read More