Set up Redis distributed caching in the AppHost

This article covers the minimum AppHost configuration required to use the Redis distributed caching client integration. The underlying hosting integration is the same Aspire.Hosting.Redis package used by the regular Redis integration — there is no separate “distributed” hosting package. For the complete AppHost API surface — data volumes, data bind mounts, persistence, Redis Insight, Redis Commander, parameters, custom environment variables, existing instances, and hosting health checks — see the Redis Hosting integration reference.

If you’re new to Redis distributed caching with Aspire, start with Get started with Redis distributed caching. For how consuming C# apps register IDistributedCache, see Connect to Redis distributed caching.

Installation

Install the 📦 Aspire.Hosting.Redis NuGet package in your AppHost project:

C#

Terminal

aspire add redis

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package Aspire.Hosting.Redis@*

XML — AppHost.csproj

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

TypeScript

Terminal

aspire add redis

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the Redis hosting integration package:

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.Redis": "13.3.0"
  }
}

Add Redis resource

Once the hosting integration is installed, add a Redis resource in your AppHost and reference it from the apps that need distributed caching:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(cache);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cache = await builder.addRedis("cache");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(cache);

// After adding all resources, run the app...

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.io/library/redis image, it creates a new Redis instance on your local machine.

2. The AppHost reference call configures a connection in the consuming project named after the referenced Redis resource, such as cache in the preceding example.

3. The consuming C# project calls AddRedisDistributedCache("cache") in Program.cs to register IDistributedCache using that connection. See Connect to Redis distributed caching for details.

Note

When you reference a Redis resource from the AppHost, Aspire makes the connection URI, hostname, port, and password available to the consuming project as environment variables. For a complete list of these properties, see Connect to Redis distributed caching.

Full AppHost API reference

The Redis distributed caching integration shares the Redis hosting integration with the rest of the Redis ecosystem. For all available AppHost APIs, see the Redis Hosting integration reference, which covers:

• WithDataVolume — persist Redis data outside the container lifecycle.
• WithDataBindMount — bind-mount a host directory into the container.
• WithPersistence — configure snapshotting interval and key-change threshold.
• WithRedisInsight / WithRedisCommander — attach management UIs.
• AddParameter for explicit port and password — override auto-generated values.
• Custom environment variables — map connection properties to app-specific variable names.
• AsExisting — connect to an externally managed Redis instance instead of starting a container.
• Hosting health checks — automatically verify the Redis container is reachable.

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.