.NET Aspire Redis®^* 输出缓存集成

项目
2025-04-30

包含： - Client 集成

了解如何使用 .NET AspireRedis 输出缓存集成。客户端集成用于注册一个由服务器支持的输出缓存提供程序，与容器镜像。

了解如何使用 .NET AspireRedis 输出缓存集成。用于将由Aspire.StackExchange.Redis.OutputCaching服务器支持的ASP.NET Core输出缓存提供程序，注册到ghcr.io/microsoft/garnet的客户端集成。

了解如何使用 .NET AspireRedis 输出缓存集成。客户端Aspire.StackExchange.Redis.OutputCaching集成用于注册由ASP.NET Core服务器支持的输出缓存提供程序到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）路径，位于主机的 Redis 容器中。有关数据绑定装载的详细信息，请参阅 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，可将它们添加到应用主机项目中的 📦Aspire.Hosting.Garnet 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，可以将它添加到你的 .Hosting.Valkey NuGet 包中，并在应用程序主机项目中使用。

.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 数据。数据绑定挂载在主机上的 Valkey 容器路径上，具体位置为 Windows 的 C:\Valkey\Data（或 /Valkey/Data 上的 Unix）。有关数据绑定装载的详细信息，请参阅 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.HealthChecks.Redis NuGet 包。

Client 集成

若要开始使用 .NET Aspire Stack Exchange Redis 输出缓存客户端集成，请安装。📦AspireStackExchange.Redis.客户端使用项目中的 OutputCaching NuGet 包，即使用输出缓存客户端的应用程序的项目。 Redis 输出缓存客户端集成注册了启用 CacheOutput 方法调用和使用 [OutputCache] 属性所需的服务，以便依赖 Redis 作为其缓存机制。

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

dotnet add package Aspire.StackExchange.Redis.OutputCaching

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

添加输出缓存

在客户端使用项目的 Program.cs 文件中，对任何 AddRedisOutputCache 调用 IHostApplicationBuilder 扩展方法，以注册输出缓存所需的服务。

builder.AddRedisOutputCache(connectionName: "cache");

提示

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

提示

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

提示

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

通过调用 UseOutputCache(IApplicationBuilder)将中间件添加到请求处理管道：

var app = builder.Build();

app.UseOutputCache();

对于最小化 API 应用，配置一个终结点，通过调用 CacheOutput 或应用 OutputCacheAttribute 来进行缓存，如以下示例所示：

app.MapGet("/cached", () => "Hello world!")
   .CacheOutput();

app.MapGet(
    "/attribute",
    [OutputCache] () => "Hello world!");

对于具有控制器的应用，请将 [OutputCache] 属性应用于操作方法。对于 Razor Pages 应用，请将属性应用于 Razor 页面类。

配置

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

使用连接字符串

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

builder.AddRedisOutputCache(connectionName: "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.OutputCaching/ConfigurationSchema.json。

使用内联委托

也可以传递 Action<StackExchangeRedisSettings> configurationSettings 委托来直接配置一些或所有选项，例如在代码中禁用运行状况检查：

builder.AddRedisOutputCache(
    "cache",
    static settings => settings.DisableHealthChecks  = true);

你还可以通过方法的委托参数来设置 ConfigurationOptions。例如，要设置连接超时：

builder.AddRedisOutputCache(
    "cache",
    static settings => settings.ConnectTimeout = 3_000);

Client 整合健康检查

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

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

.NET Aspire Stack Exchange Redis 输出缓存集成处理以下内容：

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

可观测性和遥测

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

伐木

.NET Aspire Stack Exchange Redis 输出缓存集成使用以下日志类别：

Aspire.StackExchange.Redis
Microsoft.AspNetCore.OutputCaching.StackExchangeRedis

追踪

.NET Aspire Stack Exchange Redis 输出缓存集成将通过 OpenTelemetry 发出以下跟踪活动：

OpenTelemetry.Instrumentation.StackExchangeRedis

指标

.NET Aspire Stack Exchange Redis 输出缓存集成由于 StackExchange.Redis 库的限制，目前默认不支持性能指标。

另请参阅

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

通过

.NET Aspire Redis®* 输出缓存集成

托管集成

添加 Redis 资源

使用 Redis Insights 添加 Redis 资源

使用Redis指挥官来添加Redis资源。

添加携带数据卷的 Redis 资源

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

添加 Redis 资源并保持持久性

添加 Garnet 资源

添加具有数据量的Garnet资源

添加带有数据绑定挂载的 Garnet 资源

添加具有持久性的 Garnet 资源

添加 Valkey 资源

添加带有数据量的 Valkey 资源

添加带有数据绑定挂载的 Valkey 资源

添加具有持久性的 Valkey 资源

托管集成运行状况检查

Client 集成

添加输出缓存

配置

使用连接字符串

使用配置提供者

使用内联委托

Client 整合健康检查

可观测性和遥测

伐木

追踪

指标

另请参阅

其他资源

.NET Aspire Redis®^* 输出缓存集成