Connect to Redis output caching

This page describes how ASP.NET Core apps connect to a Redis resource that’s already modeled in your AppHost and use it as an output cache store. For the AppHost API surface — adding a Redis resource, data volumes, persistence, and more — see Set up Redis output caching in the AppHost.

The recommended C# client integration is 📦 Aspire.StackExchange.Redis.OutputCaching. It registers IOutputCacheStore through dependency injection and wires up health checks and OpenTelemetry automatically using the connection information Aspire injects from the AppHost.

Connection properties

When you reference a Redis resource from a consuming project, Aspire injects each connection property as an environment variable named [RESOURCE]_[PROPERTY]. For a resource called cache, the variables are:

Property name	Environment variable	Description
Host	CACHE_HOST	The hostname or IP address of the Redis server
Port	CACHE_PORT	The port number the Redis server is listening on
Password	CACHE_PASSWORD	The password for authentication
Uri	CACHE_URI	The full connection URI: redis://:{Password}@{Host}:{Port}

Example connection URI:

redis://:p%40ssw0rd1@localhost:6379

Connect from your app

ASP.NET Core output caching is a C#-only feature — only the C# client integration is shown here. The steps below assume your AppHost adds a Redis resource named cache and references it from your ASP.NET Core project, as shown in Set up Redis output caching in the AppHost.

C#

Install the client integration

Install the 📦 Aspire.StackExchange.Redis.OutputCaching NuGet package in the consuming project:

.NET CLI

.NET CLI — Add Aspire.StackExchange.Redis.OutputCaching package

dotnet add package Aspire.StackExchange.Redis.OutputCaching

Program.cs (C# file-based app)

Program.cs

#:package Aspire.StackExchange.Redis.OutputCaching@*

PackageReference (*.csproj)

XML — Add Aspire.StackExchange.Redis.OutputCaching package reference

<PackageReference Include="Aspire.StackExchange.Redis.OutputCaching" Version="*" />

Register the output cache store

In Program.cs, call AddRedisOutputCache to register IOutputCacheStore and add the output caching middleware:

C# — Program.cs

builder.AddRedisOutputCache(connectionName: "cache");

Tip

The connectionName must match the Redis resource name declared in the AppHost. See Add Redis resource.

Then add the middleware to the request pipeline:

C# — Program.cs

var app = builder.Build();

app.UseOutputCache();

Use [OutputCache] on endpoints

For minimal API endpoints, use the CacheOutput() extension method or the [OutputCache] attribute:

C# — Program.cs

app.MapGet("/cached", () => "Hello world!")
   .CacheOutput();

app.MapGet(
    "/attribute",
    [OutputCache(Duration = 60)] () => Results.Ok("Hello world!"));

For MVC controllers, apply [OutputCache] directly to the action method:

C# — WeatherController.cs

[ApiController]
[Route("[controller]")]
public class WeatherController : ControllerBase
{
    [HttpGet]
    [OutputCache(Duration = 60)]
    public IEnumerable<WeatherForecast> Get()
    {
        // Response is cached in Redis for 60 seconds
        return GetForecasts();
    }
}

Configuration

The client integration offers three ways to supply configuration.

Connection strings. Pass the connection name to AddRedisOutputCache and add a matching entry in ConnectionStrings:

C# — Program.cs

builder.AddRedisOutputCache("cache");

JSON — appsettings.json

{
  "ConnectionStrings": {
    "cache": "localhost:6379"
  }
}

For more information, see Stack Exchange Redis configuration.

Configuration providers. The integration reads StackExchangeRedisSettings from any Microsoft.Extensions.Configuration source using the Aspire:StackExchange:Redis:OutputCaching key:

JSON — appsettings.json

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "OutputCaching": {
          "ConnectionString": "localhost:6379",
          "DisableHealthChecks": false,
          "DisableTracing": false
        }
      }
    }
  }
}

Inline delegates. Pass an Action<StackExchangeRedisSettings> to configure settings inline, for example to disable health checks:

C# — Program.cs

builder.AddRedisOutputCache(
    "cache",
    static settings => settings.DisableHealthChecks = true);

To configure the underlying ConfigurationOptions:

C# — Program.cs

builder.AddRedisOutputCache(
    "cache",
    configureOptions: options => options.ConnectTimeout = 3000);

Client integration health checks

By default, Aspire integrations enable health checks. The Redis output caching integration adds a health check that verifies the Redis instance is reachable and can execute commands. The health check is wired into the /health HTTP endpoint — all registered health checks must pass before the app is considered ready to accept traffic.

Observability and telemetry

The Aspire Redis output caching integration automatically configures logging, tracing, and metrics through OpenTelemetry.

Logging categories:

• Aspire.StackExchange.Redis

Tracing activities:

• OpenTelemetry.Instrumentation.StackExchangeRedis

Metrics are emitted through OpenTelemetry. Any of these telemetry features can be disabled through the configuration options above.

TypeScript, Go, and Python apps

Aspire.StackExchange.Redis.OutputCaching is a .NET package and ASP.NET Core output caching is a C#-only feature. If your consuming app is written in TypeScript, Go, or Python and you need to interact with the same Redis resource directly, read the Aspire-injected CACHE_URI (or CACHE_HOST / CACHE_PORT / CACHE_PASSWORD) environment variables and use any RESP-compatible client library. See Redis client integration for per-language connection details.

Registered trademark

Redis is a registered trademark of Redis Ltd. Any rights therein are reserved to Redis Ltd. Any use by Microsoft is for referential purposes only and does not indicate any sponsorship, endorsement or affiliation between Redis and Microsoft.