Set up Redis in the AppHost

This article is the reference for the Aspire Redis Hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.mts — that you use to model a Redis resource in your AppHost project.

If you’re new to the Redis integration, start with the Get started with Redis integrations guide. For how consuming apps read the connection information this page exposes, see Connect to Redis.

Installation

To start building an Aspire app that uses Redis, install the 📦 Aspire.Hosting.Redis NuGet package:

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.5.3"
  }
}

C#

Terminal

aspire add redis

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

AppHost.cs

#:package Aspire.Hosting.Redis@*

AppHost.csproj

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

Add Redis resource

Once you’ve installed the hosting integration in your AppHost project, you can add a Redis resource as shown in the following examples:

TypeScript

apphost.mts

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

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...

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...

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 Redis resource is configured with a randomly generated password by default. To set an explicit password, see Add Redis resource with parameters.

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

Note

When you reference a Redis resource from the AppHost, Aspire makes several properties available to the consuming project, such as connection URIs, hostnames, port numbers, and the password. For a complete list of these properties and per-language connection examples, see Connect to Redis.

• Redis container imageDocker Hub

  docker.io/library/redis:8.6

  Added by AddRedis()addRedis().

  Source

Tags reflect the latest defaults on the microsoft/aspire main branch, and may be newer than the version pinned by the package you install.

Add Redis resource with data volume

Add a data volume to the Redis resource as shown in the following examples:

TypeScript

apphost.mts

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

const builder = await createBuilder();

const cache = await builder.addRedis("cache");
await cache.withDataVolume({ isReadOnly: false });

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
    .WithDataVolume(isReadOnly: false);

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

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

The data volume is used to persist Redis data outside the lifecycle of its container. The data volume is mounted at the /data path in the Redis container, and when a name parameter isn’t provided, the name is generated at random. Calling WithDataVolume (or withDataVolume) also enables Redis persistence so the in-memory state survives container restarts. For more information on data volumes and details on why they’re preferred over bind mounts, see Docker docs: Volumes.

Add Redis resource with data bind mount

Add a data bind mount to the Redis resource as shown in the following examples:

TypeScript

apphost.mts

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

const builder = await createBuilder();

const cache = await builder.addRedis("cache");
await cache.withDataBindMount("C:\\Redis\\Data", { isReadOnly: false });

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
    .WithDataBindMount(
        source: @"C:\Redis\Data",
        isReadOnly: false);

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

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

Note

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

Data bind mounts rely on the host machine’s filesystem to persist Redis data across container restarts. The data bind mount is mounted at the C:\Redis\Data on Windows (or /Redis/Data on Unix) path on the host machine in the Redis container. As with WithDataVolume, this call also enables persistence. For more information on data bind mounts, see Docker docs: Bind mounts.

Add Redis resource with persistence

To configure Redis snapshot persistence explicitly, call WithPersistence (or withPersistence) alongside a data volume or bind mount:

TypeScript

apphost.mts

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

const builder = await createBuilder();

const cache = await builder.addRedis("cache");
await cache.withDataVolume();
await cache.withPersistence({
    interval: 5 * 60 * 1000,
    keysChangedThreshold: 100,
});

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
    .WithDataVolume()
    .WithPersistence(
        interval: TimeSpan.FromMinutes(5),
        keysChangedThreshold: 100);

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

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

The preceding code adds explicit persistence to the Redis resource by snapshotting data at the configured interval whenever the configured number of keys changes. The C# AppHost accepts a TimeSpan for interval; the TypeScript AppHost accepts the same value as milliseconds.

Add Redis resource with parameters

When you want to explicitly provide the port and password used by the Redis container, you can pass them as parameters:

TypeScript

apphost.mts

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

const builder = await createBuilder();

const password = await builder.addParameter("password", { secret: true });

const cache = await builder.addRedis("cache", { port: 6379, password });

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var password = builder.AddParameter("password", secret: true);

var cache = builder.AddRedis("cache", port: 6379, password: password);

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

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

When no password parameter is provided, Aspire generates a strong password automatically using the CreateDefaultPasswordParameter method.

Add Redis resource with Redis Insight

Redis Insight is a free graphical interface for analyzing Redis data. Add it to the Redis resource as shown in the following examples:

TypeScript

apphost.mts

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

const builder = await createBuilder();

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

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

The preceding code adds a container based on the docker.io/redis/redisinsight image. The Redis Insight UI is available from the Aspire dashboard and connects automatically to the Redis resource.

• RedisInsight container imageCompanion · RedisDocker Hub

  docker.io/redis/redisinsight:3.4

  Added by WithRedisInsight()withRedisInsight().

  Source

Tags reflect the latest defaults on the microsoft/aspire main branch, and may be newer than the version pinned by the package you install.

Configure Redis Insight host port

To configure the host port for the Redis Insight container, use the configureContainer callback as shown in the following examples:

TypeScript

apphost.mts

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

const builder = await createBuilder();

const cache = await builder.addRedis("cache");
await cache.withRedisInsight({
    configureContainer: async redisInsight => {
        await redisInsight.withHostPort(8001);
    }
});

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
    .WithRedisInsight(redisInsight => redisInsight.WithHostPort(8001));

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

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

The preceding code adds and configures the host port for the Redis Insight container. The host port is otherwise randomly assigned.

Add Redis resource with Redis Commander

Redis Commander is a Node.js web application for viewing, editing, and managing a Redis database. Add it to the Redis resource as shown in the following examples:

TypeScript

apphost.mts

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

const builder = await createBuilder();

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

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

The preceding code adds a container based on the ghcr.io/joeferner/redis-commander image. The Redis Commander UI is available from the Aspire dashboard and connects automatically to the Redis resource.

• Redis Commander container imageCompanion · RedisGitHub Container Registry

  ghcr.io/joeferner/redis-commander:latest

  Added by WithRedisCommander()withRedisCommander().

  Source

Tags reflect the latest defaults on the microsoft/aspire main branch, and may be newer than the version pinned by the package you install.

Configure Redis Commander host port

To configure the host port for the Redis Commander container, use the configureContainer callback as shown in the following examples:

TypeScript

apphost.mts

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

const builder = await createBuilder();

const cache = await builder.addRedis("cache");
await cache.withRedisCommander({
    configureContainer: async redisCommander => {
        await redisCommander.withHostPort(8081);
    }
});

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
    .WithRedisCommander(redisCommander => redisCommander.WithHostPort(8081));

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

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

The preceding code adds and configures the host port for the Redis Commander container. The host port is otherwise randomly assigned.

Add Redis resource with clear command

The WithClearCommand method adds a CLEAR command button to the Aspire dashboard for the Redis resource. When clicked, it flushes all keys from the Redis database, which is useful during development to reset cache state without restarting the container.

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Note

The TypeScript AppHost doesn’t currently expose a withClearCommand() API for Redis. This feature is only available in the C# AppHost.

Pass custom environment variables

By default, Aspire injects the Redis connection information using variable names derived from the resource name (for example, CACHE_URI, CACHE_HOST, CACHE_PORT, CACHE_PASSWORD). If your consuming app expects a different set of environment variable names, pass individual connection properties from the AppHost:

TypeScript

apphost.mts

import { createBuilder, EndpointProperty } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const cache = await builder.addRedis("cache");
const cacheEndpoint = await cache.primaryEndpoint();
const cacheHost = await cacheEndpoint.property(EndpointProperty.Host);
const cachePort = await cacheEndpoint.property(EndpointProperty.Port);

await builder.addNodeApp("my-app", "./app", "index.js")
    .withReference(cache)
    .withEnvironment("REDIS_HOST", cacheHost)
    .withEnvironment("REDIS_PORT", cachePort)
    .withEnvironment("REDIS_PASSWORD", await cache.passwordParameter());

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var app = builder.AddExecutable("my-app", "node", "app.js", ".")
    .WithReference(cache)
    .WithEnvironment(context =>
    {
        context.EnvironmentVariables["REDIS_HOST"] = cache.Resource.PrimaryEndpoint.Property(EndpointProperty.Host);
        context.EnvironmentVariables["REDIS_PORT"] = cache.Resource.PrimaryEndpoint.Property(EndpointProperty.Port);
        context.EnvironmentVariables["REDIS_PASSWORD"] = cache.Resource.PasswordParameter;
    });

builder.Build().Run();

Connect to an existing Redis instance

To reference an externally managed Redis instance instead of running one as a container, use AddConnectionString:

TypeScript

apphost.mts

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

const builder = await createBuilder();

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

await builder.addNodeApp("my-app", "./app", "index.js")
    .withReference(cache);

// After adding all resources, run the app...
await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

With AddConnectionString and addConnectionString, Aspire resolves cache from ConnectionStrings:cache (or environment variable ConnectionStrings__cache) in the AppHost configuration. Consuming apps receive that value as a single connection string, not deconstructed Redis resource-specific connection-property variables such as CACHE_HOST, CACHE_PORT, or CACHE_URI.

Connection properties

For the full reference of Redis resource connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to Redis.

Hosting integration health checks

The Redis hosting integration automatically adds a health check for the Redis resource. The health check verifies that the Redis instance is running and that a connection can be established to it.

The hosting integration relies on the 📦 AspNetCore.HealthChecks.Redis NuGet package.