The goal

End state

By the end you'll have a Redis container running as a managed resource in the Aspire dashboard, and a service reading and writing through an injected IDistributedCache.

This is the same shape as wiring up a database with the SQL Server resource: the cache is a managed resource - a container Aspire owns - and the consuming project never sees a hand-written connection string. If you want the machinery underneath AddRedis and WithReference, that is Inside Aspire's AppHost.

Prerequisites

Aspire CLI
13.2 or later - check with aspire --version
.NET SDK
9.0 or later
Container runtime
Docker Desktop or Podman, running - Aspire pulls the Redis image into it
Starting point
An Aspire solution with an AppHost and at least one referenced project (the service that will cache)
Assumed knowledge
You've run aspire run before and know your way around the dashboard

Steps

1

Add the Redis hosting integration to the AppHost

Shellsolution root
dotnet add AppHost package Aspire.Hosting.Redis

ExpectedAspire.Hosting.Redis is added to AppHost.csproj; AddRedis and RedisResource are now in scope.

2

Model a Redis resource and wire it to your service

Declare the container in the AppHost and reference it from the project that needs it. WaitFor holds the service until Redis passes its health check.

C#AppHost.cs
var builder = DistributedApplication.CreateBuilder(args); // Redis runs from the docker.io/library/redis image, // with a password generated for you each run. var cache = builder.AddRedis("cache"); builder.AddProject<Projects.Api>("api") .WithReference(cache) // inject the connection string .WaitFor(cache); // wait until cache is healthy builder.Build().Run();

ExpectedThe solution builds. At run time the api project receives a ConnectionStrings__cache environment variable.

3

Add the caching client integration to your service

This goes in the consuming project, not the AppHost. It brings the IDistributedCache wiring backed by StackExchange.Redis.

Shellsolution root
dotnet add Api package Aspire.StackExchange.Redis.DistributedCaching

ExpectedAspire.StackExchange.Redis.DistributedCaching is added to Api.csproj; AddRedisDistributedCache is in scope.

4

Register the distributed cache

The name must match the resource name from step 2 - that is how Aspire matches the injected connection string.

C#Api/Program.cs
var builder = WebApplication.CreateBuilder(args); builder.AddServiceDefaults(); builder.AddRedisDistributedCache("cache"); // matches AddRedis("cache")

ExpectedIDistributedCache resolves from DI; there is no localhost:6379 string anywhere in your code or config.

5

Cache a response, then run it

Read through the cache first; compute and write back only on a miss. Then start the whole topology with the Aspire CLI.

C#Api/Program.cs
var app = builder.Build(); app.MapGet("/forecast", async (IDistributedCache cache) => { var hit = await cache.GetStringAsync("forecast"); if (hit is not null) return Results.Text(hit); var fresh = Forecast.Compute(); // the expensive bit await cache.SetStringAsync("forecast", fresh, new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5) }); return Results.Text(fresh); }); app.Run();

ExpectedRun aspire run. The dashboard opens; the first GET /forecast computes, a second within 5 minutes returns instantly from Redis.

Verify

You're done when every one of these holds:

  • The dashboard lists a cache resource of type Container, state Running.
  • The cache resource logs show Redis Ready to accept connections.
  • The api resource's environment shows ConnectionStrings__cache injected by Aspire.
  • First GET /forecast is a miss (it computes); the next is served from cache, visibly faster.
  • The forecast key exists in Redis - confirm via the dashboard's resource commands or redis-cli KEYS *.

Troubleshooting

SymptomStartup throws Unable to resolve service for type 'IDistributedCache'.

FixYou added the hosting package to the AppHost but not the client package to the service. Install Aspire.StackExchange.Redis.DistributedCaching in the consuming project and call AddRedisDistributedCache("cache") there.

SymptomThe service starts before Redis and the first calls fail with a connection refused.

FixAdd .WaitFor(cache) to the project in the AppHost so it waits for the container's health check before launching.

SymptomThe cache resource is stuck on Starting, or the image pull fails.

FixYour container runtime isn't running. Start Docker Desktop or Podman, then re-run aspire run - Aspire pulls docker.io/library/redis on first launch.

References