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

项目
12/12/2024

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

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

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

托管集成

托管集成 Redis 将 Redis 资源建模为 RedisResource 类型。若要访问此类型和 API，可以将它添加到 📦Aspire.Hosting.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 数据。数据绑定挂载位于主机上的 Redis 容器内，挂载路径在 Windows 的 C:\Redis\Data 或 Unix上的 /Redis/Data。有关数据绑定装载的详细信息，请参阅 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 数据。数据绑定挂载位于主机上 Garnet 容器的 Windows 上的 C:\Garnet\Data（或 Unix上的 /Garnet/Data）路径中。有关数据绑定装载的详细信息，请参阅 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 是否正在运行，并可以建立与该 server 的连接。

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

Client 集成

若要开始 .NET AspireRedis 分布式缓存集成，请安装 📦Aspire。StackExchange。Redis。client消耗项目中的 DistributedCaching NuGet 包，即使用 Redis 分布式缓存 client的应用程序的项目。

.NET CLI
PackageReference

dotnet add package Aspire.StackExchange.Redis.DistributedCaching

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

添加 Redisclient

在您的 client使用项目的 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 依赖项注入。

添加键 Redisclient

在某些情况下，可能需要使用不同的连接名称注册多个 IDistributedCache 实例。若要注册密钥 Redis 客户端，请调用 AddKeyedRedisDistributedCache 方法：

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

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

public class ExampleService(
    [FromKeyedServices("chat")] IDistributedCache chatCache,
    [FromKeyedServices("product")] IDistributedCache productCache)
{
    // Use caches...
}

有关密钥服务的详细信息，请参阅 .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。它通过使用 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> 委托来设置部分或全部内联选项，例如配置 DisableTracing：

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

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

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

运行状况检查

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

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

添加 StackExchange.Redis 运行状况检查，尝试打开连接并在连接失败时抛出异常。
与 /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

指标

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

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 Redisclient

默认情况下，在 Redis 托管集成中进行调用 AddAzureRedis 时，它会配置 📦 MicrosoftAzureStackExchangeRedis NuGet 包来启用身份验证：

.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.AddRedisDistributedCache("cache", configureOptions: options =>
{
    options.Defaults = configurationOptions.Defaults;
});

有关详细信息，请参阅 MicrosoftAzureStackExchangeRedis 代码库。

另请参阅

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

添加 Redisclient

添加键 Redisclient

配置

使用连接字符串

使用配置提供程序

使用内联委托

运行状况检查

可观测性和遥测

伐木

描图

指标

Azure Redis 托管集成

添加 Azure Cache for Redisserver 资源

添加分布式 Azure Cache for Redisclient

另请参阅

其他资源

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