redis-app-host.md

ms.topic
include

The Redis hosting integration models a Redis resource as the xref:Aspire.Hosting.ApplicationModel.RedisResource type. To access this type and APIs for expressing them as resources in your app host project, add the 📦 Aspire.Hosting.Redis NuGet package:

.NET CLI

dotnet add package Aspire.Hosting.Redis

PackageReference

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

---

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add Redis resource

In your app host project, call xref:Aspire.Hosting.RedisBuilderExtensions.AddRedis* on the builder instance to add a Redis resource:

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

When .NET Aspire adds a container image to the app host, as shown in the preceding example with the docker.io/Redis/Redis image, it creates a new Redis instance on your local machine. A reference to your Redis resource (the cache variable) is added to the ExampleProject.

The xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A method configures a connection in the ExampleProject named "cache". For more information, see Container resource lifecycle.

Tip

If you'd rather connect to an existing Redis instance, call xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString* instead. For more information, see Reference existing resources.

Add Redis resource with Redis Insights

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

Redis Insights is a free graphical interface for analyzing Redis data across all operating systems and Redis deployments with the help of our AI assistant, Redis Copilot. .NET Aspire adds another container image docker.io/redis/redisinsight to the app host that runs the commander app.

Note

To configure the host port for the RedisInsightResource chain a call to the WithHostPort API and provide the desired port number.

Add Redis resource with Redis Commander

To add the Redis Commander to the Redis resource, call the xref:Aspire.Hosting.RedisBuilderExtensions.WithRedisCommander* method:

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

Redis Commander is a Node.js web application used to view, edit, and manage a Redis Database. .NET Aspire adds another container image docker.io/rediscommander/redis-commander to the app host that runs the commander app.

Tip

To configure the host port for the xref:Aspire.Hosting.Redis.RedisCommanderResource chain a call to the xref:Aspire.Hosting.RedisBuilderExtensions.WithHostPort* API and provide the desired port number.

Add Redis resource with data volume

To add a data volume to the Redis resource, call the xref:Aspire.Hosting.RedisBuilderExtensions.WithDataVolume* method on the Redis resource:

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

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 and when a name parameter isn't provided, the name is generated at random. For more information on data volumes and details on why they're preferred over bind mounts, see Docker docs: Volumes.

Add Redis resource with data bind mount

To add a data bind mount to the Redis resource, call the xref:Aspire.Hosting.RedisBuilderExtensions.WithDataBindMount* method:

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

[!INCLUDE data-bind-mount-vs-volumes]

Data bind mounts rely on the host machine's filesystem to persist the Redis data across container restarts. The data bind mount is mounted at the C:\Redis\Data on Windows (or /Redis/Data on Unix) path on the host machine in the Redis container. For more information on data bind mounts, see Docker docs: Bind mounts.

Add Redis resource with persistence

To add persistence to the Redis resource, call the xref:Aspire.Hosting.RedisBuilderExtensions.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);

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

// After adding all resources, run the app...

The preceding code adds persistence to the Redis resource by taking snapshots of the Redis data at a specified interval and threshold. The interval is time between snapshot exports and the keysChangedThreshold is the number of key change operations required to trigger a snapshot. For more information on persistence, see Redis docs: Persistence.