Valkey integration

Valkey is a Redis fork and complies with the Redis serialization protocol (RESP). It’s a high-performance key/value datastore that supports a variety of workloads such as caching, message queues, and can act as a primary database. The Valkey integration enables you to connect to existing Valkey instances, or create new instances from Aspire with the docker.io/valkey/valkey container image.

Hosting integration

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

Aspire CLI

Aspire CLI — Ajouter le package Aspire.Hosting.Valkey

aspire add valkey

La CLI Aspire est interactive ; choisissez le résultat approprié lorsque demandé :

Aspire CLI — Exemple de sortie

Select an integration to add:

> valkey (Aspire.Hosting.Valkey)
> Other results listed as selectable options...

Note

S'il n'y a qu'un seul résultat, il est sélectionné automatiquement. Vous devez quand même confirmer la version.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Valkey@*

PackageReference (*.csproj)

XML — Ajouter la référence de package Aspire.Hosting.Valkey

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

Add Valkey resource

In your AppHost project, call AddValkey on the builder instance to add a Valkey resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Astuce

If you’d rather connect to an existing Valkey instance, call AsExisting instead.

Add Valkey resource with data volume

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

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Add Valkey resource with data bind mount

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

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

Note

Data bind mounts have limited functionality compared to volumes, and when you use a bind mount, a file or directory on the host machine is mounted into a container.

Add Valkey resource with persistence

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

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Connection properties

When you reference a Valkey resource using WithReference, the following connection properties are made available to the consuming project:

Valkey

The Valkey resource exposes the following connection properties:

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

Example connection string:

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

Note

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

Hosting integration health checks

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

Client integration

Valkey is Redis-compatible, so you use the same Redis client packages. To get started, install the 📦 Aspire.StackExchange.Redis NuGet package:

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

In the Program.cs file of your client-consuming project, call the AddRedisClient extension method to register an IConnectionMultiplexer:

builder.AddRedisClient(connectionName: "cache");

Astuce

The connectionName parameter must match the name used when adding the Valkey resource in the AppHost project.

You can then retrieve the IConnectionMultiplexer instance using dependency injection:

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

Configuration and other client features

Since Valkey is Redis-compatible, all Redis client configuration, keyed services, health checks, and observability features work the same way. See the Redis integration page for complete client integration documentation.

Distributed caching and output caching

Valkey also supports Redis distributed caching and output caching. Install the respective packages:

• For distributed caching: 📦 Aspire.StackExchange.Redis.DistributedCaching
• For output caching: 📦 Aspire.StackExchange.Redis.OutputCaching

See Redis Distributed Caching and Redis Output Caching for usage details.