Get started with the 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.

In this introduction, you’ll see how to install and use the Aspire Valkey integrations in a simple configuration. If you already have this knowledge, see Valkey hosting integration for full reference details.

Note

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire Valkey hosting integration in your Aspire 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="*" />

Next, in the AppHost project, create instances of Valkey resources and pass them to the consuming client projects:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

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.

Set up client integration

Valkey is Redis-compatible, so you use the same Redis client packages. To get started, install the 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="*" />

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

See also

• Valkey hosting integration
• Valkey client integration
• Redis integration