.NET Aspire Redis®^* 集成

项目
12/16/2024

Redis 是用于缓存、矢量搜索和 NoSQL 数据库的世界最快数据平台。通过 .NET AspireRedis 集成，可以连接到现有 Redis 实例，或使用 docker.io/library/redis 容器映像从 .NET 创建新实例。

Garnet 是来自 Microsoft Research 的高性能缓存存储，符合 Redis 序列化协议（RESP）。 .NET Aspire Redis 集成使你能够连接到现有的 Garnet 实例，或使用 ghcr.io/microsoft/garnet 容器映像从 .NET 创建新实例。

Valkey 是一个 Redis 分支，符合 Redis 序列化协议（RESP）。它是一种高性能键/值数据存储，支持各种工作负荷，例如缓存、消息队列，并且可以充当主数据库。 .NET Aspire Redis 集成使你能够连接到现有的 Valkey 实例，或使用 docker.io/valkey/valkey 容器映像从 .NET 创建新实例。

托管集成

托管集成 Redis 将 Redis 资源建模为 RedisResource 类型。若要访问这种类型和可以将其添加到应用主机项目的 API，请在应用程序主机中使用的 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 数据。数据卷被装载在 /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 数据在容器重启之间持久化。在宿主机的 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 命令行界面
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 是否正在运行，并可以建立与该 server 的连接。

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

Client 集成

若要开始使用 .NET Aspire Stack Exchange Redisclient 集成，请安装 📦Aspire。StackExchange。Redis 使用 client项目中的 NuGet 包，即使用 Redisclient的应用程序的项目。 Redis client 集成注册 IConnectionMultiplexer 实例，该实例可用于与 Redis交互。

.NET 命令行界面
包引用

dotnet add package Aspire.StackExchange.Redis

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

添加 Redisclient

在 client消耗项目的 Program.cs 文件中，对任何 IHostApplicationBuilder 调用 AddRedisClient 扩展方法，以注册 IConnectionMultiplexer，以便通过依赖项注入容器使用。该方法采用连接名称参数。

builder.AddRedisClient(connectionName: "cache");

提示

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

提示

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

提示

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

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

public class ExampleService(IConnectionMultiplexer connectionMux)
{
    // Use connection multiplexer...
}

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

添加键 Redisclient

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

builder.AddKeyedRedisClient(name: "chat");
builder.AddKeyedRedisClient(name: "queue");

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

public class ExampleService(
    [FromKeyedServices("chat")] IConnectionMultiplexer chatConnectionMux,
    [FromKeyedServices("queue")] IConnectionMultiplexer queueConnectionMux)
{
    // Use connections...
}

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

配置

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

使用连接字符串

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

builder.AddRedis("cache");

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

builder.AddGarnet("cache");

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

builder.AddValkey("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.AddRedisClient(
    "cache",
    static settings => settings.DisableTracing = true);

Client 集成健康检查

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

.NET Aspire Stack Exchange Redis 集成处理以下内容：

当 StackExchangeRedisSettings.DisableHealthChecks 为 false时，添加健康检查，该检查将尝试连接到容器实例。
与 /health HTTP 终端集成，该终端规定所有注册的健康检查都必须通过，这样应用程序才能被视为可以接收流量。

可观测性和遥测

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

伐木

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

Aspire.StackExchange.Redis

追踪

.NET Aspire Stack Exchange Redis 集成将使用 OpenTelemetry产生以下跟踪活动：

OpenTelemetry.Instrumentation.StackExchangeRedis

指标

由于 StackExchange.Redis 库的限制，.NET Aspire Stack Exchange 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 Redisclient

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

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

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

另请参阅

*：Redis 是 Redis 有限公司的注册商标。其中的任何权利都保留给 Redis 有限公司。微软的任何用法仅供参考，并不表示 Redis 和微软之间存在任何赞助、认可或关联。回到顶部？

通过

.NET Aspire Redis®* 集成

托管集成

添加 Redis 资源

使用 Redis Insights 添加 Redis 资源

用Redis指挥官添加Redis资源

使用数据存储卷添加 Redis 资源

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

添加具有持久性 Redis 资源

添加 Garnet 资源

添加带有数据量的 Garnet 资源

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

添加具有持久性的 Garnet 资源

添加“Valkey”资源

添加具有数据卷的 Valkey 资源

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

添加具有持久性的 Valkey 资源

托管集成运行状况检查

Client 集成

添加 Redisclient

添加键 Redisclient

配置

使用连接字符串

使用配置提供程序

使用内联委托

Client 集成健康检查

可观测性和遥测

伐木

追踪

指标

Azure Redis 托管集成

添加 Azure Cache for Redisserver 资源

添加 Azure Cache for Redisclient

另请参阅

其他资源

.NET Aspire Redis®^* 集成