Redis integration

Redis® is the world’s fastest data platform for caching, vector search, and NoSQL databases. The Aspire Redis integration enables you to connect to existing Redis instances, or create new instances from .NET with the docker.io/library/redis container image.

Hosting integration

The Redis hosting integration models a Redis resource as the RedisResource type. To access this type and APIs, add the 📦 Aspire.Hosting.Redis NuGet package in your AppHost project:

aspire add redis

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> redis (Aspire.Hosting.Redis)
> Other results listed as selectable options...

#:package Aspire.Hosting.Redis@*

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

Add Redis resource

In your AppHost project, call AddRedis on the builder instance to add a Redis resource:

var builder = DistributedApplication.CreateBuilder(args);

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

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

When Aspire adds a container image to the AppHost, it creates a new Redis instance on your local machine.

Add Redis resource with Redis Insights

To add Redis Insights to the Redis resource, call the WithRedisInsight method:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Redis Insights is a free graphical interface for analyzing Redis data across all operating systems and Redis deployments.

Add Redis resource with Redis Commander

To add Redis Commander to the Redis resource, call the WithRedisCommander method:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Redis Commander is a Node.js web application used to view, edit, and manage a Redis Database.

Add Redis resource with data volume

To add a data volume to the Redis resource, call the WithDataVolume method:

var builder = DistributedApplication.CreateBuilder(args);

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

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

The data volume is used to persist the Redis data outside the lifecycle of its container. The data volume is mounted at the /data path in the Redis container.

Add Redis resource with data bind mount

To add a data bind mount to the Redis resource, call the WithDataBindMount method:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Add Redis resource with persistence

To add persistence to the Redis resource, call the WithPersistence method with either the data volume or data bind mount:

var builder = DistributedApplication.CreateBuilder(args);

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

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

The preceding code adds persistence to the Redis resource by taking snapshots of the Redis data at a specified interval and threshold.

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.

Using with non-.NET applications

The Redis hosting integration can be used with any application technology. When you use WithReference to reference a Redis resource, connection information is automatically injected as environment variables:

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.AddRedis("cache")
    .WithLifetime(ContainerLifetime.Persistent);

// Configure a non-.NET application with Redis access
var app = builder.AddExecutable("my-app", "python", "app.py", ".")
    .WithReference(redis) // Provides ConnectionStrings__cache
    .WithEnvironment(context =>
    {
        context.EnvironmentVariables["REDIS_HOST"] = redis.Resource.PrimaryEndpoint.Property(EndpointProperty.Host);
        context.EnvironmentVariables["REDIS_PORT"] = redis.Resource.PrimaryEndpoint.Property(EndpointProperty.Port);
    });

Client integration

To get started with the Aspire Redis client integration, install the 📦 Aspire.StackExchange.Redis NuGet package:

dotnet add package Aspire.StackExchange.Redis

#:package Aspire.StackExchange.Redis@*

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

Add Redis client

In the Program.cs file of your client-consuming project, call the AddRedisClient extension method to register an IConnectionMultiplexer for use via the dependency injection container:

builder.AddRedisClient(connectionName: "cache");

You can then retrieve the IConnectionMultiplexer instance using dependency injection:

public class ExampleService(IConnectionMultiplexer connectionMux)
{
    // Use connection multiplexer...
}

Add keyed Redis client

There might be situations where you want to register multiple IConnectionMultiplexer instances with different connection names. To register keyed Redis clients, call the AddKeyedRedisClient method:

builder.AddKeyedRedisClient(name: "chat");
builder.AddKeyedRedisClient(name: "queue");

Then retrieve the instances:

public class ExampleService(
    [FromKeyedServices("chat")] IConnectionMultiplexer chatConnectionMux,
    [FromKeyedServices("queue")] IConnectionMultiplexer queueConnectionMux)
{
    // Use connections...
}

For more information on keyed services, see .NET dependency injection: Keyed services.

Configuration

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling AddRedis:

builder.AddRedis("cache");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

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

For more information on how to format this connection string, see the Stack Exchange Redis configuration docs.

Use configuration providers

The Redis client integration supports Microsoft.Extensions.Configuration. It loads the StackExchangeRedisSettings from configuration using the Aspire:StackExchange:Redis key. Example appsettings.json:

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

Use inline delegates

You can pass the delegate to set up options inline:

builder.AddRedisClient(
    "cache",
    static settings => settings.DisableTracing = true);

Client integration health checks

By default, Aspire integrations enable health checks for all services. The Redis integration adds a health check that verifies the Redis instance is reachable and can execute commands.

Observability and telemetry

Logging

The Redis integration uses the following log categories:

Aspire.StackExchange.Redis

Tracing

The Redis integration will emit the following tracing activities using OpenTelemetry:

OpenTelemetry.Instrumentation.StackExchangeRedis

Metrics

The Redis integration emits metrics using OpenTelemetry.

FAQ Collaborate Community Discuss Watch