Connect to Redis

This page describes how consuming apps connect to a Redis resource that’s already modeled in your AppHost. For the AppHost API surface — adding a Redis resource, data volumes, persistence, management UIs, and more — see Redis Hosting integration.

When you reference a Redis resource from your AppHost, Aspire injects the connection information into the consuming app as environment variables. Your app can either read those environment variables directly — the pattern works the same from any language — or, in C#, use the Aspire Redis client integration for automatic dependency injection, health checks, and telemetry.

Connection properties

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called cache becomes CACHE_URI.

The Redis resource exposes the following connection properties:

Property Name	Description
Host	The hostname or IP address of the Redis server
Port	The port number the Redis server is listening on
Password	The password for authentication
Uri	The connection URI, with the format redis://:{Password}@{Host}:{Port}

Example connection string:

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

Connect from your app

Pick the language your consuming app is written in. Each example assumes your AppHost adds a Redis resource named cache and references it from the consuming app.

C#

For C# apps, the recommended approach is the Aspire Redis client integration. It registers an IConnectionMultiplexer through dependency injection and adds health checks and telemetry automatically. If you’d rather read environment variables directly, see the Read environment variables in C# section at the end of this tab.

Install the client integration

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

.NET CLI

.NET CLI — Add Aspire.StackExchange.Redis package

dotnet add package Aspire.StackExchange.Redis

Program.cs (C# file-based app)

Program.cs

#:package Aspire.StackExchange.Redis@*

PackageReference (*.csproj)

XML — Add Aspire.StackExchange.Redis package reference

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

Add the Redis client

In Program.cs, call AddRedisClient on your IHostApplicationBuilder to register an IConnectionMultiplexer:

C# — Program.cs

builder.AddRedisClient(connectionName: "cache");

Consiglio

The connectionName must match the Redis resource name from the AppHost. For more information, see Add Redis resource.

Resolve the connection multiplexer through dependency injection:

C# — ExampleService.cs

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

Add keyed Redis clients

To register multiple IConnectionMultiplexer instances with different connection names, use AddKeyedRedisClient:

C# — Program.cs

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

Then resolve each instance by key:

C# — ExampleService.cs

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

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

Configuration

The Aspire Redis client integration offers multiple ways to provide configuration.

Connection strings. When using a connection string from the ConnectionStrings configuration section, pass the connection name to AddRedisClient:

C# — Program.cs

builder.AddRedisClient("cache");

The connection string is resolved from the ConnectionStrings section:

JSON — appsettings.json

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

For more information, see Stack Exchange Redis configuration.

Configuration providers. The client integration supports Microsoft.Extensions.Configuration. It loads StackExchangeRedisSettings from appsettings.json (or any other configuration source) by using the Aspire:StackExchange:Redis key:

JSON — appsettings.json

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

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

C# — Program.cs

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

Redis client builder pattern

Use AddRedisClientBuilder to configure Redis clients with a fluent API, which is especially useful when combining Redis with distributed caching or Azure authentication:

C# — Program.cs

builder.AddRedisClientBuilder("cache")
    .WithDistributedCache(options =>
    {
        options.InstanceName = "MyApp";
    });

To enable Azure Entra ID authentication for Azure Cache for Redis, add the 📦 Aspire.Microsoft.Azure.StackExchangeRedis NuGet package and chain a call to WithAzureAuthentication():

C# — Program.cs

builder.AddRedisClientBuilder("cache")
    .WithAzureAuthentication()
    .WithDistributedCache(options =>
    {
        options.InstanceName = "MyApp";
    });

Auto activation

Redis client connections support auto activation to prevent startup deadlocks and improve application reliability. Auto activation is disabled by default but can be enabled using the DisableAutoActivation option:

C# — Program.cs

builder.AddRedisClient("cache", c => c.DisableAutoActivation = false);

Nota

In a future version of Aspire, auto activation is planned to be enabled by default. When this change occurs, you’ll need to explicitly set DisableAutoActivation = true if you want to maintain the lazy initialization behavior.

Client integration health checks

Aspire client integrations enable health checks by default. The Redis client 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, where all registered health checks must pass before the app is considered ready to accept traffic.

Observability and telemetry

The Aspire Redis client 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.

Distributed caching and output caching

Redis also works with the Aspire distributed-caching and output-caching client integrations because they’re built on top of the same Redis client. Install the respective packages and follow their guides:

• Aspire.StackExchange.Redis.DistributedCaching — see Get started with Redis distributed caching.
• Aspire.StackExchange.Redis.OutputCaching — see Get started with Redis output caching.

Read environment variables in C#

If you prefer not to use the Aspire client integration, you can read the Aspire-injected connection URI from the environment and pass it to 📦 StackExchange.Redis directly:

C# — Program.cs

using StackExchange.Redis;

var connectionString = Environment.GetEnvironmentVariable("CACHE_URI");
var mux = await ConnectionMultiplexer.ConnectAsync(connectionString!);

var db = mux.GetDatabase();
// Use db to interact with Redis...

Go

Use go-redis, the most actively maintained Go client for the RESP protocol:

Terminal

go get github.com/redis/go-redis/v9

Read the injected environment variable and connect:

Go — main.go

package main

import (
    "context"
    "os"
    "github.com/redis/go-redis/v9"
)

func main() {
    // Read the Aspire-injected connection URI
    opt, err := redis.ParseURL(os.Getenv("CACHE_URI"))
    if err != nil {
        panic(err)
    }

    rdb := redis.NewClient(opt)
    defer rdb.Close()

    _ = rdb.Ping(context.Background()).Err()
}

Python

Install redis-py, the official Python client for RESP servers including Redis:

Terminal

pip install redis

Read the injected environment variable and connect:

Python — app.py

import os
import redis

# Read the Aspire-injected connection URI
client = redis.from_url(os.getenv("CACHE_URI"))

client.ping()
# Use client to interact with Redis...

TypeScript

Install ioredis, the most popular RESP client for Node.js:

Terminal

npm install ioredis

Read the injected environment variables and connect:

TypeScript — index.ts

import Redis from 'ioredis';

// Read Aspire-injected connection properties
const client = new Redis({
    host: process.env.CACHE_HOST,
    port: Number(process.env.CACHE_PORT),
    password: process.env.CACHE_PASSWORD,
});

await client.ping();

Or use the connection URI directly:

TypeScript — Connect with URI

import Redis from 'ioredis';

const client = new Redis(process.env.CACHE_URI!);

Consiglio

If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost. See Pass custom environment variables in the Hosting integration reference.