Connect to Azure Cache for Redis

This page describes how consuming apps connect to an Azure Cache for Redis resource that’s already modeled in your AppHost. For the AppHost API surface — adding a managed Redis resource, running as a local container, Entra ID versus access key authentication, and more — see Azure Cache for Redis Hosting integration.

When you reference an Azure Cache for 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 Azure Managed Redis resource exposes the following connection properties:

Property Name	Description
Host	The hostname of the Azure Cache for Redis endpoint
Port	The port number. Uses the default Azure Cache for Redis TLS port when connecting to Azure; uses the configured container port when running locally via RunAsContainer
Password	The access key. Empty when using Entra ID authentication; populated when using WithAccessKeyAuthentication or running as a local container
Uri	The connection URI. In Azure mode: redis://{Host}; when running as a local container: redis://[:{Password}@]{Host}:{Port}

Example connection strings:

Uri (Azure mode, Entra ID):    redis://myredis.redis.cache.windows.net
Uri (local container mode):    redis://:p%40ssw0rd1@localhost:6379

Connect from your app

Pick the language your consuming app is written in. Each example assumes your AppHost adds an Azure Managed 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");

İpucu

The connectionName must match the Azure Managed Redis resource name from the AppHost. For more information, see Add Azure Managed 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: "primary-cache");
builder.AddKeyedRedisClient(name: "secondary-cache");

Then resolve each instance by key:

C# — ExampleService.cs

public class ExampleService(
    [FromKeyedServices("primary-cache")] IConnectionMultiplexer primaryMux,
    [FromKeyedServices("secondary-cache")] IConnectionMultiplexer secondaryMux)
{
    // Use connections...
}

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

Azure Entra ID authentication

To enable Microsoft Entra ID (managed identity) authentication for Azure Cache for Redis in C#, install the 📦 Aspire.Microsoft.Azure.StackExchangeRedis NuGet package and use the AddRedisClientBuilder API with WithAzureAuthentication:

C# — Program.cs

builder.AddRedisClientBuilder("cache")
    .WithAzureAuthentication();

This configures the Redis client to obtain access tokens using the app’s managed identity when running in Azure, without storing passwords in connection strings.

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": "myredis.redis.cache.windows.net:6380,ssl=True,password=..."
  }
}

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": "myredis.redis.cache.windows.net:6380,ssl=True",
        "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);

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

Azure Cache for 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 properties from the environment and configure 📦 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 Azure Cache for 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 variables and connect. Azure Cache for Redis requires TLS, so configure the client accordingly:

Go — main.go

package main

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

func main() {
    // Read Aspire-injected connection properties
    host := os.Getenv("CACHE_HOST")
    port := os.Getenv("CACHE_PORT")
    password := os.Getenv("CACHE_PASSWORD")

    portNum, _ := strconv.Atoi(port)

    rdb := redis.NewClient(&redis.Options{
        Addr:      host + ":" + port,
        Password:  password,
        DB:        0,
        TLSConfig: &tls.Config{ServerName: host},
    })
    defer rdb.Close()

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

    // Use rdb to interact with Azure Cache for Redis...
    _ = portNum
}

When running as a local container via RunAsContainer, you can use the simpler URI-based connection instead:

Go — main.go (local container)

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()
}

Not

When using Entra ID authentication (the default in Azure mode), no password is injected. To authenticate with managed identity from Go, use the Azure SDK for Go to obtain a token and pass it as the password to the Redis client.

Python

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

Terminal

pip install redis

Read the injected environment variables and connect. Azure Cache for Redis requires TLS:

Python — app.py

import os
import redis

# Read Aspire-injected connection properties
host = os.getenv("CACHE_HOST")
port = int(os.getenv("CACHE_PORT", "6380"))
password = os.getenv("CACHE_PASSWORD")  # empty when using Entra ID

# Connect with TLS enabled for Azure
client = redis.Redis(
    host=host,
    port=port,
    password=password or None,
    ssl=True,
    ssl_cert_reqs=None,
)

client.ping()
# Use client to interact with Azure Cache for Redis...

When running as a local container via RunAsContainer, you can use the simpler URI-based connection:

Python — app.py (local container)

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

Not

When using Entra ID authentication (the default in Azure mode), CACHE_PASSWORD is empty. To authenticate with managed identity from Python, use the azure-identity package to obtain a token and pass it as the password to the Redis client.

TypeScript

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

Terminal

npm install ioredis

Read the injected environment variables and connect. Azure Cache for Redis requires TLS:

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 ?? 6380),
    password: process.env.CACHE_PASSWORD || undefined,
    tls: { servername: process.env.CACHE_HOST },
});

await client.ping();
// Use client to interact with Azure Cache for Redis...

When running as a local container via RunAsContainer, you can use the simpler URI-based connection:

TypeScript — Connect with URI (local container)

import Redis from 'ioredis';

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

Not

When using Entra ID authentication (the default in Azure mode), CACHE_PASSWORD is empty. To authenticate with managed identity from TypeScript, use the @azure/identity package to obtain a token and pass it as the password to the Redis client.

İpucu

If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost. See Use existing Azure resources for guidance on customizing environment variable injection.