5-integrations.md

.NET Aspire Integrations

.NET Aspire integrations are a curated suite of NuGet packages specifically selected to facilitate the integration of cloud-native applications with prominent services and platforms, e.g. Redis, PostgreSQL, etc. Each integration furnishes essential cloud-native functionalities through either automatic provisioning or standardized configuration patterns.

.NET Aspire integrations come in two distinct flavors: hosting integrations, and client integrations. Hosting integrations are used to model and configure various resources in a .NET Aspire app, while client integrations are used to map configuration to various client libraries.

There is an ever growing list .NET Aspire integrations created and shipped by Microsoft and the community. .NET Aspire is flexible and anyone can create their own package to integrate with their own services.

Let's improve our application by adding an integration to it. We will add a integration that will help us to connect to a Redis cache to improve our API performance.

Add Redis Integration to App Host

To add the Redis hosting integration to our App Host, we need to install the Aspire.Hosting.Redis NuGet package. This package provides the necessary pieces to configure the service in the App Host. Redis is provided through a container image in this workshop, and when we start the .NET Aspire App Host, it will automatically download the Redis container image and start the Redis server.

With the NuGet package installed, we can add Redis to our App Host:

1. Open the Program.cs file in the AppHost project.

2. Add the following code under var builder = DistributedApplication.CreateBuilder(args);

   var cache = builder.AddRedis("cache");

   Here, we have configured the Redis cache with the name cache. This name is used to identify the cache in the Api or MyWeatherHub.

3. Update the api in the App Host with a reference to the cache.

   var api = builder.AddProject<Projects.Api>("api")
                    .WithReference(cache);

4. Additionally, we could configure Redis Commander, a Redis management tool. As part of the Aspire.Hosting.Redis package, Redis Commander is available in the same integration. To add Redis Commander, update the code adding the Redis resource to call the WithRedisCommander() method on the returned builder:

   var cache = builder.AddRedis("cache")
                      .WithRedisCommander();

Run the application

We haven't made any changes to the Api or MyWeatherHub projects, but we can see the Redis cache start when we start the App Host.

Important

Since Redis runs in a container you will need to ensure that Docker is running on your machine.

1. Ensure Docker Desktop or Podman is running.

2. Start the App Host project.

3. You will see both the Redis container and Redis Commander container download and start in both the dashboard and in Docker Desktop.

   

Integrate Output Caching in API

There are two types of caching that we could integrate into our ASP.NET Core applications:

• Output caching: A configurable, extensible caching method for storing entire HTTP responses for future requests.
• Distributed caching: A cache shared by multiple app servers that allows you to cache specific pieces of data. A distributed cache is typically maintained as an external service to the app servers that access it and can improve the performance and scalability of an ASP.NET Core app.

We will add the Output caching Redis client integration to our Api project. This integration will help us to cache the response of our API in Redis cache.

1. Install the Aspire.StackExchange.Redis.OutputCaching NuGet package in the Api project to get access to the Redis APIs.

2. Open the Program.cs file in the Api project.

3. Add the following code under the var builder = WebApplication.CreateBuilder(args); at the top of the file:

   builder.AddRedisOutputCache("cache");

   Note that we are using the "cache" name to reference the Redis cache that we configured in the App Host.

4. The NwsManager has already been configured to use Output caching, but with a memory cache. We will update it to use the Redis cache. Open the NwsManager.cs file in the Data folder.

5. In the NwsManagerExtensions class you will find a AddNwsManager method.

6. DELETE the following code:

   // Add default output caching
   services.AddOutputCache(options =>
   {
       options.AddBasePolicy(builder => builder.Cache());
   });

   Because we configured the application to use Redis cache in the Program.cs file, we no longer need to add the default output caching policy.

Run the updated application

1. Start the App Host project and open the MyWeatherHub project from the dashboard.

2. Click on a city and then click on it again. You will see that the response is cached and the second request is much faster than the first one under the Traces tab.

   

3. You can also see the cached response in Redis Commander. Open Redis Commander by clicking on the cache-commander endpoint in the dashboard. Under stats you will see connections and commands processed.

   

4. In addition, you can see logs for the Redis cache and Redis Commander in the Console tab.

   

Custom Redis Containers

.NET Aspire integrations are flexible and customizable. By default, the Redis integration uses a Redis container image from Docker Hub. However, you can use your own Redis container image by providing the image name and tag after the AddRedis method. For example, if you have a custom Redis container image such as Garnet, you can provide the image registry, name, and tag in the App Host as follows:

var cache = builder.AddRedis("cache")
    .WithImageRegistry("ghcr.io")
    .WithImage("microsoft/garnet")
    .WithImageTag("latest");

Note: there is a new Garnet integration that simplifies this integration, but the above highlights the flexibility of the integrations.

1. Run the application and you will now see Garnet running in the dashboard and in Docker Desktop.

   

2. You can also see the logs for Garnet in the Console tab.

   

Summary

In this section, we added a Redis hosting integration to the App Host and Redis output caching client integration in the API. We saw how the response was cached in the Redis cache and how the second and subsequent requests were much faster than the first one. We also saw how to use Redis Commander to manage the Redis cache.

There are many more Aspire integrations available that you can use to integrate with your services. You can find the list of available integrations in the .NET Aspire documentation.

A natural next step would be to integrate a database or leverage Azure Redis Cache as a hosted solution. Integrations for these and more are available on NuGet.