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

项目
12/12/2024

了解如何使用 .NET AspireRedis 输出缓存集成。 Aspire.StackExchange.Redis.OutputCaching client 集成用于注册由 Redisserver 支持的 ASP.NET Core 输出缓存提供程序，并使用 docker.io/library/redis 容器映像。

了解如何使用 .NET AspireRedis 输出缓存集成。 Aspire.StackExchange.Redis.OutputCaching client 集成用于注册一个由 Garnetserver 支持的 ASP.NET Core 输出缓存提供程序，该提供程序通过 ghcr.io/microsoft/garnet 容器映像实现。

了解如何使用 .NET AspireRedis 输出缓存集成。 Aspire.StackExchange.Redis.OutputCaching client 集成用于向 docker.io/valkey/valkey 容器映像注册由 Valkeyserver 支持的 ASP.NET Core 输出缓存提供程序。

托管集成

托管集成 Redis 将 Redis 资源建模为 RedisResource 类型。若要访问此类型和 API，可将其添加到 📦Aspire托管Redis NuGet 包中的应用程序主机项目。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Redis

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

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

添加 Redis 资源

在应用主机项目中，对 builder 实例调用 AddRedis 以添加 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 方法在名为 "cache"的 ExampleProject 中配置连接。有关详细信息，请参阅容器资源生命周期。

提示

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

提示

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

添加 Redis 资源，附带数据卷

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

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 数据。数据卷装载在 Redis 容器中的 /data 路径，如果未提供 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（或 Unix上的 /Redis/Data）路径，位于主机的 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 包。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Garnet

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

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

添加 Garnet 资源

在应用主机项目中，对 builder 实例调用 AddGarnet 以添加 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 方法在名为 "cache"的 ExampleProject 中配置连接。有关详细信息，请参阅容器资源生命周期。

提示

如果想要连接到现有的 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 数据。数据绑定装载装载安装在 Windows 上的 C:\Garnet\Data（或 Unix上的 /Garnet/Data）路径上的 Garnet 容器中的主机上。有关数据绑定装载的详细信息，请参阅 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。应用主机项目中的 Hosting.Valkey NuGet 包。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Valkey

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

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

添加 Valkey 资源

在应用主机项目中，对 builder 实例调用 AddValkey 以添加 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 方法在名为 "cache"的 ExampleProject 中配置连接。有关详细信息，请参阅容器资源生命周期。

提示

如果想要连接到现有的 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（或 Unix上 /Valkey/Data）路径上的 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 会自动为合适的资源类型添加健康检查。运行状况检查会验证 server 是否正在运行，并验证是否可以建立与其的连接。

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

Client 集成

若要开始 .NET Aspire Stack Exchange Redis 输出缓存 client 集成，请在 client消耗项目中安装 📦Aspire.StackExchange.Redis.OutputCaching NuGet 包，即使用输出缓存 client的应用程序的项目。

.NET 命令行界面
PackageReference

dotnet add package Aspire.StackExchange.Redis.OutputCaching

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

添加输出缓存

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

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。使用 Aspire:StackExchange:Redis 键从配置中加载 StackExchangeRedisSettings。配置某些选项的示例 appsettings.json：

{
  "Aspire": {
    "StackExchange": {
      "Redis": {
        "ConnectionString": "localhost:6379",
        "DisableHealthChecks": true,
        "DisableTracing": false
      }
    }
  }
}

有关完整的 Redisclient 集成 JSON 架构，请参阅 Aspire。StackExchange。Redis/ConfigurationSchema。json。

使用内联委托

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

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

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

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

健康检查

默认情况下，.NET.NET Aspire 集成为所有服务启用健康检查。有关详细信息，请参阅 .NET.NET Aspire 集成概述。

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

添加 StackExchange.Redis 健康检查，尝试打开连接并在连接失败时抛出异常。
与 /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 库的限制，目前默认不支持性能指标。

Azure Redis 托管集成

若要将 Redis 资源部署到 Azure，请安装 📦Aspire.Hosting.Azure.Redis NuGet 包。

.NET 命令行界面（CLI）
PackageReference

dotnet add package Aspire.Hosting.Azure.Redis

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

添加 Azure Cache for Redisserver 资源

安装 .NET Aspire 托管 AzureRedis 包后，请在应用程序主机项目中调用 AddAzureRedis 扩展方法。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddAzureRedis("azcache")

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

上述 AddAzureRedis 调用将 Redisserver 资源配置为 Azure Cache for Redis。

重要

默认情况下，AddAzureRedis 配置 Microsoft Entra ID 身份验证。这需要对需要连接到这些资源的应用程序进行更改，例如 client 集成。

添加 Azure Cache for Redis 输出 client

默认情况下，当您在 Redis 托管集成中调用 AddAzureRedis 时，它会配置 Microsoft 📦、Azure、 NuGet 包 StackExchangeRedis 以启用身份验证：

.NET 命令行界面
PackageReference

dotnet add package Microsoft.Azure.StackExchangeRedis

<PackageReference Include="Microsoft.Azure.StackExchangeRedis"
                  Version="*" />

可以通过 client 集成和 Microsoft.Azure.StackExchangeRedis来消费 Redis 连接。请考虑以下配置代码：

var azureOptionsProvider = new AzureOptionsProvider();

var configurationOptions = ConfigurationOptions.Parse(
    builder.Configuration.GetConnectionString("cache") ?? 
    throw new InvalidOperationException("Could not find a 'cache' connection string."));

if (configurationOptions.EndPoints.Any(azureOptionsProvider.IsMatch))
{
    await configurationOptions.ConfigureForAzureWithTokenCredentialAsync(
        new DefaultAzureCredential());
}

builder.AddRedisOutputCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

有关详细信息，请参阅 MicrosoftAzure.StackExchangeRedis 仓库。

另请参阅

*：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 集成

添加输出缓存

配置

使用连接字符串

使用配置提供者

使用内联委托

健康检查

可观测性和遥测

伐木

追踪

指标

Azure Redis 托管集成

添加 Azure Cache for Redisserver 资源

添加 Azure Cache for Redis 输出 client

另请参阅

其他资源

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