.NET Aspire Redis ^* 分布式缓存集成®

2025-04-16

包含： - Client 集成

了解如何使用 .NET AspireRedis 分布式缓存集成。 Aspire.StackExchange.Redis.DistributedCaching 库用于注册一个由服务器支持的 Redis 提供程序，并结合 docker.io/library/redis 容器映像。

了解如何使用 .NET AspireRedis 分布式缓存集成。 Aspire.StackExchange.Redis.DistributedCaching 库用于注册由 Garnet 服务器支持的 IDistributedCache 提供程序，并在 ghcr.io/microsoft/garnet 容器映像中使用。

了解如何使用 .NET AspireRedis 分布式缓存集成。 Aspire.StackExchange.Redis.DistributedCaching 库用于注册一个由 Valkey 服务器支持的 IDistributedCache 提供程序，并使用 docker.io/valkey/valkey 容器映像。

托管集成

托管集成 Redis 将 Redis 资源建模为 RedisResource 类型。若要访问此类型和 API，以便将其表示为应用主机项目中的资源，请添加 📦Aspire.Hosting.Redis NuGet 包：

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.Redis

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

有关详细信息，请参阅 dotnet add package 或在 .NET 应用程序中管理包依赖项。

添加 Redis 资源

在应用主机项目中，对 AddRedis 实例调用 builder 以添加 Redis 资源：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

当 .NET.NET Aspire 向应用主机添加容器映像时，例如上例中使用的 docker.io/Redis/Redis 映像，它会在本地计算机上创建一个新的 Redis 实例。对 Redis 资源的引用（cache 变量）将添加到 ExampleProject。

WithReference 方法在名为 ExampleProject 的 "cache" 中配置连接。有关详细信息，请参阅容器资源生命周期。

提示

如果想要连接到现有 Redis 实例，请改为调用 AddConnectionString。有关详细信息，请参阅引用现有资源。

使用 Redis Insights 添加 Redis 资源

若要将 Redis Insights 添加到 Redis 资源，请调用 WithRedisInsight 方法：

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 是一个免费的图形界面，借助我们的 AI 助手 Redis Copilot，可以分析所有操作系统的 Redis 数据和 Redis 部署。 .NET .NET Aspire 向运行指挥官应用的应用主机添加另一个容器映像 docker.io/redis/redisinsight。

注意

要为 RedisInsightResource 链配置主机端口，请调用 WithHostPort API，并提供所需的端口号。

添加 Redis 资源并配合 Redis 指挥官

若要将 Redis 指挥官添加到 Redis 资源，请调用 WithRedisCommander 方法：

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 是用于查看、编辑和管理 Node.js 数据库的 Redis Web 应用程序。 .NET .NET Aspire 向运行指挥官应用的应用主机添加另一个容器映像 docker.io/rediscommander/redis-commander。

提示

要为 RedisCommanderResource 链配置主机端口，请调用 WithHostPort API，并提供所需的端口号。

将具有数据卷的 Redis 资源添加

若要将数据卷添加到 Redis 资源，请在 WithDataVolume 资源上调用 Redis 方法：

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

数据卷用于在容器的生命周期之外保留 Redis 数据。数据卷被装载在 /data 容器的 Redis 路径中，当未提供 name 参数时，名称将被随机生成。有关数据卷的更多信息，以及它们为何比绑定挂载更受青睐的原因，请参阅Docker 文档：卷。

使用数据绑定挂载来添加 Redis 资源

要将数据绑定挂载添加到 Redis 资源中，请调用 WithDataBindMount 方法：

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

重要

与卷相比，绑定挂载的功能有限，而卷提供更好的性能、可移植性和安全性，使它们更适用于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定挂载依赖于主机文件系统，以便在容器重启时持久化 Redis 数据。数据绑定挂载在主机的 Windows 系统（或 C:\Redis\Data 系统）的 /Redis/Data 路径中，位于 Unix 容器内。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

添加 Redis 资源并保持其持久性

若要将持久性添加到 Redis 资源，请通过数据卷或数据绑定挂载调用 WithPersistence 方法。

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

前面的代码通过按指定的间隔和阈值拍摄 Redis 数据的快照，将持久性添加到 Redis 资源。 interval 是快照导出和 keysChangedThreshold 之间的时间，是触发快照所需的密钥更改操作数。有关持久性的详细信息，请参阅 Redis 文档：持久性。

Garnet 托管集成将 Garnet 资源建模为 GarnetResource 类型。要访问此类型和 API，可以在 📦 项目的 📦 NuGet 包中添加它。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.Garnet

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

有关详细信息，请参阅 dotnet add package 或在 .NET 应用程序中管理包依赖项。

添加 Garnet 资源

在应用主机项目中，对 AddGarnet 实例调用 builder 以添加 Garnet 资源：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

.NET .NET Aspire 将容器映像添加到应用主机时，如前面的示例中使用 ghcr.io/microsoft/garnet 映像所示，它会在本地计算机上创建新的 Garnet 实例。对 Garnet 资源的引用（cache 变量）已添加至 ExampleProject。

WithReference 方法在名为 ExampleProject 的 "cache" 中配置连接。有关详细信息，请参阅容器资源生命周期。

提示

如果想要连接到现有的 Garnet 实例，请改为调用 AddConnectionString。有关详细信息，请参阅引用现有资源。

添加带有数据量的 Garnet 资源

若要向 Garnet 资源添加数据卷，请在 Garnet 资源上调用 AddGarnet 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

数据卷用于在容器的生命周期之外保留 Garnet 数据。数据卷装载在 Garnet 容器中的 /data 路径，如果未提供 name 参数，则会随机生成名称。有关数据卷的更多信息，以及它们为何比绑定挂载更受青睐的原因，请参阅Docker 文档：卷。

通过数据挂载添加 Garnet 资源

若要向 Garnet 资源添加数据绑定挂载，请调用 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

重要

数据绑定挂载依赖于主机的文件系统，以便在容器重启时维持 Garnet 数据的持久性。数据绑定挂载位于主机上 Garnet 容器的 Windows 上的 C:\Garnet\Data（或 /Garnet/Data上的 Unix）路径中。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

添加具有持久性的 Garnet 资源

若要为 Garnet 资源添加持久性，请使用数据卷或数据绑定挂载来调用 WithPersistence 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

前面的代码通过按指定的间隔和阈值拍摄 Garnet 数据的快照，将持久性添加到 Redis 资源。 interval 是快照导出和 keysChangedThreshold 之间的时间，是触发快照所需的密钥更改操作数。有关持久性的详细信息，请参阅 Redis 文档：持久性。

Valkey 托管集成将 Valkey 资源建模为 ValkeyResource 类型。若要访问此类型和 API，可在 📦 项目中将其添加到您的 Aspire 中。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.Valkey

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

有关详细信息，请参阅 dotnet add package 或在 .NET 应用程序中管理包依赖项。

添加 Valkey 资源

在应用主机项目中，对 AddValkey 实例调用 builder 以添加 Valkey 资源：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

当 .NET.NET Aspire 向应用主机添加容器映像时，如前面的示例所示，其中包含 docker.io/valkey/valkey 映像，它会在本地计算机上创建新的 Valkey 实例。对 Valkey 资源（cache 变量）的引用已被添加到 ExampleProject。

WithReference 方法在名为 ExampleProject 的 "cache" 中配置连接。有关详细信息，请参阅容器资源生命周期。

提示

如果想要连接到现有的 Valkey 实例，请改为调用 AddConnectionString。有关详细信息，请参阅引用现有资源。

添加包含数据量的 Valkey 资源

若要将数据卷添加到 Valkey 资源，请在 Valkey 资源上调用 AddValkey 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

数据卷用于在容器的生命周期之外保留 Valkey 数据。数据卷被挂载在 Valkey 容器中的 /data 路径，如果未提供 name 参数，则会随机生成名称。有关数据卷的更多信息，以及它们为何比绑定挂载更受青睐的原因，请参阅Docker 文档：卷。

添加使用数据绑定挂载的 Valkey 资源

若要将数据绑定挂载添加到 Valkey 资源，请调用 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

重要

数据绑定挂载依赖于主机的文件系统，以便在容器重启时持久保留 Valkey 数据。数据绑定装载安装在 Windows 上的 C:\Valkey\Data（或 /Valkey/Data上 Unix）路径上的 Valkey 容器中的主机上。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

添加具有持久性特性的 Valkey 资源

若要向 Valkey 资源添加持久性，请用数据卷或数据绑定挂载来调用 WithPersistence 方法。

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

前面的代码通过按指定的间隔和阈值拍摄 Valkey 数据的快照，将持久性添加到 Redis 资源。 interval 是快照导出和 keysChangedThreshold 之间的时间，是触发快照所需的密钥更改操作数。有关持久性的详细信息，请参阅 Redis 文档：持久性。

主办集成健康检查

Redis 托管集成会自动为合适的资源类型添加健康检查。运行状况检查验证服务器是否正在运行，并可以建立与服务器的连接。

托管集成依赖于 📦 AspNetCore.HealthChecksRedis NuGet 包。

Client 集成

若要开始 .NET AspireRedis 分布式缓存集成，请在使用客户端的项目中安装 📦Aspire。StackExchange.Redis.DistributedCaching. NuGet 包，即那些使用 Redis 分布式缓存客户端的应用程序项目。在 Redis 客户端集成中，您可以注册一个可用于与 IDistributedCache交互的 Redis 实例。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

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

添加 Redis 客户端

在客户端使用项目的 Program.cs 文件中，调用 AddRedisDistributedCache 扩展来注册分布式缓存所需的服务，并添加 IDistributedCache，以便通过依赖项注入容器使用。

builder.AddRedisDistributedCache(connectionName: "cache");

提示

connectionName 参数必须与在应用主机项目中添加 Redis 资源时使用的名称匹配。有关详细信息，请参阅添加 Redis 资源。

提示

connectionName 参数必须与在应用主机项目中添加 Garnet 资源时使用的名称匹配。有关详细信息，请参阅添加 Garnet 资源。

提示

connectionName 参数必须与在应用主机项目中添加 Valkey 资源时使用的名称匹配。有关详细信息，请参阅添加 Valkey 资源。

然后，可以使用依赖项注入检索 IDistributedCache 实例。例如，若要从服务检索缓存，

public class ExampleService(IDistributedCache cache)
{
    // Use cache...
}

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加加密的 Redis 客户端

由于其限制，无法同时注册多个 IDistributedCache 实例。但是，在某些情况下，可能需要注册多个 Redis 客户端，并将特定 IDistributedCache 实例用于特定连接名称。若要注册一个密钥的Redis客户端以用于IDistributedCache服务，请调用该AddKeyedRedisDistributedCache方法。

builder.AddKeyedRedisClient(name: "chat");
builder.AddKeyedRedisDistributedCache(name: "product");

然后，可以使用依赖项注入检索 IDistributedCache 实例。例如，若要从示例服务检索连接，

public class ExampleService(
    [FromKeyedServices("chat")] IConnectionMultiplexer chatConnectionMux,
    IDistributedCache productCache)
{
    // Use product cache...
}

有关密钥服务的详细信息，请参阅 .NET 依赖项注入：键式服务。

配置

.NET Aspire Redis 分布式缓存集成提供了多个选项，用于根据项目的要求和约定配置 Redis 连接。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 builder.AddRedisDistributedCache时提供连接字符串的名称：

builder.AddRedisDistributedCache("cache");

然后，将从 ConnectionStrings 配置部分检索连接字符串：

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

有关如何设置此连接字符串格式的详细信息，请参阅 Stack Exchange Redis 配置文档。

使用配置提供程序

.NET Aspire Stack Exchange Redis 分布式缓存集成支持 Microsoft.Extensions.Configuration。它通过使用 StackExchangeRedisSettings 键从配置中加载 Aspire:StackExchange:Redis。配置某些选项的示例 appsettings.json：

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConfigurationOptions": {
          "ConnectTimeout": 3000,
          "ConnectRetry": 2
        },
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

有关完整的 Redis 分布式缓存客户端集成 JSON 架构，请参阅 Aspire/StackExchange/Redis/DistributedCaching/ConfigurationSchema.json/。

使用内联委托

还可以使用 Action<StackExchangeRedisSettings> 委托来直接设置部分或全部选项，例如配置 DisableTracing：

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

您还可以使用方法的委托参数来配置 Action<ConfigurationOptions> configureOptions。例如，您可以将连接超时设置为：

builder.AddRedisDistributedCache(
    "cache",
     null,
     static options => options.ConnectTimeout = 3_000);

Client 整合健康检查

默认情况下，所有服务的.NET.NET Aspire客户端集成都启用了状态检查。同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。有关详细信息，请参阅：

C# 应用的健康检查
运行状况检查在 ASP.NET Core 中

.NET Aspire Redis 分布式缓存集成处理以下内容：

当 StackExchangeRedisSettings.DisableHealthChecks 为 false时添加运行状况检查，该检查将尝试连接到容器实例。
与 /health HTTP 端点集成，该端点规定所有注册的健康检查必须通过，应用才能被视为已准备好接收流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时被称为 可观察性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Redis 分布式缓存集成使用以下日志类别：

Aspire.StackExchange.Redis
Microsoft.Extensions.Caching.StackExchangeRedis

追踪

.NET Aspire Redis 分布式缓存集成将通过 OpenTelemetry发出以下跟踪活动：

OpenTelemetry.Instrumentation.StackExchangeRedis

指标

由于 .NET Aspire 库的限制，RedisStackExchange.Redis 分布式缓存集成目前目前不支持指标。

另请参阅

*：Redis 是 Redis 有限公司的注册商标。其所有权利均归 Redis 有限公司所有。Microsoft 的任何使用仅供参考，并不表示 Redis 和 Microsoft 之间的任何赞助、认可或关联。返回顶部？

通过

.NET Aspire Redis * 分布式缓存集成®

托管集成

添加 Redis 资源

使用 Redis Insights 添加 Redis 资源

添加 Redis 资源并配合 Redis 指挥官

将具有数据卷的 Redis 资源添加

使用数据绑定挂载来添加 Redis 资源

添加 Redis 资源并保持其持久性

添加 Garnet 资源

添加带有数据量的 Garnet 资源

通过数据挂载添加 Garnet 资源

添加具有持久性的 Garnet 资源

添加 Valkey 资源

添加包含数据量的 Valkey 资源

添加使用数据绑定挂载的 Valkey 资源

添加具有持久性特性的 Valkey 资源

主办集成健康检查

Client 集成

添加 Redis 客户端

添加加密的 Redis 客户端

配置

使用连接字符串

使用配置提供程序

使用内联委托

Client 整合健康检查

可观测性和遥测

伐木

追踪

指标

另请参阅

其他资源

.NET Aspire Redis ^* 分布式缓存集成®