在 .NET Aspire 中使用 Redis 分布式缓存：Aspire.StackExchange.Redis.DistributedCaching 组件完全指南

在 .NET Aspire 中使用 Redis 分布式缓存Aspire.StackExchange.Redis.DistributedCaching 组件完全指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire导读本文以 src/Components/Aspire.StackExchange.Redis.DistributedCaching/README.md 为骨架系统讲解 .NET Aspire 中基于 StackExchange.Redis 的IDistributedCache集成组件从包安装、AddRedisDistributedCache注册、依赖注入消费到连接字符串、配置提供程序、内联委托三种配置方式再到 Keyed 多实例注册与 AppHost 端 Redis 编排。结合仓库源码AspireRedisDistributedCacheExtensions.cs、AspireRedisExtensions.cs、StackExchangeRedisSettings.cs与单元测试说明组件底层如何实现连接复用、健康检查、日志与遥测帮助读者在真实项目中原样落地并理解其内部机制。组件定位与核心价值Aspire.StackExchange.Redis.DistributedCaching是 Aspire 组件体系中面向分布式缓存场景的 Redis 实现它在依赖注入DI容器中注册一个连接 Redis® 服务器的 IDistributedCache 实例并自动启用对应的健康检查health check、日志logging与遥测telemetry。从 Aspire.StackExchange.Redis.DistributedCaching.csproj 可以看出该包的官方描述为 A Redis® implementation for IDistributedCache that integrates with Aspire, including health checks, logging, and telemetry其实现依赖两个关键单元Microsoft.Extensions.Caching.StackExchangeRedis包提供RedisCache这一IDistributedCache的标准 Redis 实现同仓库的 Aspire.StackExchange.Redis 组件提供IConnectionMultiplexer客户端注册、连接字符串解析、健康检查与 OpenTelemetry 追踪的完整管线。简言之本组件 Aspire 对 StackExchange.Redis 客户端的托管封装 IDistributedCache的标准实现二者在 DI 容器中被组装起来。快速开始前提条件一个可连接的 Redis 服务器及其主机名hostname供客户端连接使用。至少需要提供一个有效的主机地址组件才能建立连接。安装 NuGet 包在消费端项目如 Web API 服务中通过 .NET CLI 安装组件包dotnet add package Aspire.StackExchange.Redis.DistributedCaching如果后续还要在 AppHost 编排端注册 Redis 资源请另行安装宿主集成包见下文AppHost 扩展一节。注册服务在项目的Program.cs即 Aspire 组件约定中的AppHost.cs场景之外的消费者项目入口中调用AddRedisDistributedCache扩展方法该方法接收一个**连接名称connection name**参数用于从配置中检索连接字符串builder.AddRedisDistributedCache(cache);该扩展方法定义于 AspireRedisDistributedCacheExtensions.cs其签名如下public static void AddRedisDistributedCache( this IHostApplicationBuilder builder, string connectionName, ActionStackExchangeRedisSettings? configureSettings null, ActionConfigurationOptions? configureOptions null)源码显示它做了两件事调用builder.AddRedisClient(connectionName, configureSettings, configureOptions)注册IConnectionMultiplexer为单例singleton并联动注册重试、健康检查、日志与遥测调用内部方法AddRedisDistributedCacheCore通过AddStackExchangeRedisCache注册IDistributedCache并将RedisCacheOptions.ConnectionMultiplexerFactory指向 DI 中解析出的IConnectionMultiplexer实现连接复用——同一应用内多个组件共享同一条 Redis 连接而非各自新建。通过依赖注入消费注册完成后即可在任意由 DI 构建的类型中注入IDistributedCache。例如在 Web API 控制器中private readonly IDistributedCache _cache; public ProductsController(IDistributedCache cache) { _cache cache; }随后就可以使用_cache.GetStringAsync(key)、_cache.SetStringAsync(key, value, options)等标准IDistributedCacheAPI 读写缓存。注册多个 Keyed IDistributedCache 实例当应用需要多个相互独立、配置各异的 Redis 缓存时可以使用键控服务keyed services模式。Aspire 提供两条路线路线一基于 AddRedisClientBuilder 链式注册借助AddRedisClientBuilder扩展方法返回的 AspireRedisClientBuilder支持链式调用可先注册一个无键的IConnectionMultiplexer再在其上挂载一个键控的IDistributedCachebuilder.AddRedisClientBuilder(redis) // 以连接名 redis 注册无键 IConnectionMultiplexer .WithKeyedDistributedCache(distributedCache); // 以键 distributedCache 注册键控 IDistributedCache注意IConnectionMultiplexer使用的键与IDistributedCache使用的键相互独立。在上例中连接复用键是redis对应ConnectionStrings:redis而缓存服务的解析键是distributedCache。WithKeyedDistributedCache也支持可选的ActionRedisCacheOptions参数例如设置缓存键前缀options options.InstanceName distributedCache。路线二AddKeyedRedisDistributedCache也可直接使用AddKeyedRedisDistributedCache(name, ...)它同时以name作为IConnectionMultiplexer的服务键和连接字符串检索名并读取Aspire:StackExchange:Redis:{name}配置节见 AspireRedisDistributedCacheExtensions.cs。键控服务消费示例在 Web API 控制器中使用[FromKeyedServices]按键解析private readonly IDistributedCache _cache; public ProductsController([FromKeyedServices(distributedCache)] IDistributedCache cache) { _cache cache; }源码层面的实现细节从 AspireRedisDistributedCacheExtensions.cs 可以看到键控缓存的底层实现由于AddStackExchangeRedisCache只支持无键的IDistributedCache组件通过AddKeyedSingletonIDistributedCache(name, ...)自行创建RedisCache实例并从IOptionsMonitorRedisCacheOptions获取命名选项后注入ConnectionMultiplexerFactory。源码注释同时指出该方案的一个权衡自建RedisCache无法利用 .NET 10 内部类RedisCacheImpl因此在无法添加库名前缀这一处日志及 HybridCache 的HC库名前缀添加上行为略有不同。对应单元测试 AspireRedisDistributedCacheExtensionsTests.csCanAddMultipleKeyedCachingServicesBuilder验证了注册三个不同 Redis 连接的键控缓存后各IConnectionMultiplexer与各IDistributedCache互不相同Assert.NotSame写入第一个缓存的数据只落在第一个 Redis 服务器上且键名带InstanceName前缀如dcache1key1。配置项详解组件提供多种配置途径可按项目约定灵活组合。核心约束至少提供一个主机名才能建立连接。配置的最终合并优先级从 AspireRedisExtensions.cs 的实现顺序可推断大致为配置节绑定 → 连接字符串覆盖 → 内联委托覆盖。方式一使用连接字符串组件会从ConnectionStrings配置节中按连接名检索连接字符串。调用时传入连接名builder.AddRedisDistributedCache(myRedisConnectionName);对应的配置如appsettings.json{ ConnectionStrings: { myRedisConnectionName: localhost:6379 } }连接字符串格式遵循 StackExchange.Redis 的 Basic Configuration 语法支持host:port、host:port,passwordxxx,abortConnectfalse等形式。源码中ConfigurationOptionsFactoryAspireRedisExtensions.cs会调用ConfigurationOptions.Parse(connectionString)将连接字符串解析为ConfigurationOptions对象。若最终ConfigurationOptions.EndPoints为空组件会抛出InvalidOperationException提示在ConnectionStrings:{connectionName}或{配置节}:ConnectionString中提供有效连接字符串。方式二使用配置提供程序IConfiguration组件支持Microsoft.Extensions.Configuration会加载StackExchangeRedisSettings和ConfigurationOptions配置键为Aspire:StackExchange:Redis对应源码常量DefaultConfigSectionName。若使用AddKeyedRedisDistributedCache则读取Aspire:StackExchange:Redis:{name}节。示例appsettings.json{ Aspire: { StackExchange: { Redis: { ConfigurationOptions: { ConnectTimeout: 3000, ConnectRetry: 2 }, DisableHealthChecks: true, DisableTracing: false } } } }其中ConfigurationOptions下的属性直接绑定到 StackExchange.Redis 的ConfigurationOptions如ConnectTimeout、ConnectRetry、Ssl、Password等具体属性清单以 StackExchange.Redis 文档为准。StackExchangeRedisSettings的全部属性定义于 StackExchangeRedisSettings.cs属性类型默认值说明ConnectionStringstring?null连接 Redis 服务器的逗号分隔配置字符串DisableHealthChecksboolfalse是否禁用 Redis 健康检查DisableTracingboolfalse是否禁用 OpenTelemetry 追踪DisableAutoActivationbooltrue是否禁用自动激活启用自动激活时连接在启动阶段建立而非首次使用时建立可避免首次从 DI 解析时阻塞线程此外组件会在AddRedis健康检查注册时使用健康检查名StackExchange.Redis无键或StackExchange.Redis_{connectionName}键控便于在 Aspire Dashboard 中区分多个 Redis 实例。该包的 ConfigurationSchema.json 还声明了Microsoft.Extensions.Caching.StackExchangeRedis的日志级别配置项为 IDE 提供配置智能提示。方式三使用内联委托Inline Delegates可以在调用时通过ActionStackExchangeRedisSettings委托以代码方式设置部分或全部设置例如禁用健康检查builder.AddRedisDistributedCache(cache, settings settings.DisableHealthChecks true);也可以通过ActionConfigurationOptions委托configureOptions命名参数配置ConfigurationOptions例如设置连接超时builder.AddRedisDistributedCache(cache, configureOptions: options options.ConnectTimeout 3000);两个委托分别在设置从配置读取之后被调用见方法 XML 注释与 AspireRedisExtensions.cs 的调用顺序因此内联委托拥有最高的配置优先级适合覆盖或补充配置文件中的值。三种方式的关系与优先级源码AddRedisClient的合并逻辑AspireRedisExtensions.cs展示了完整顺序从Aspire:StackExchange:Redis及其命名子节绑定StackExchangeRedisSettings若ConnectionStrings:{connectionName}存在则覆盖settings.ConnectionString调用configureSettings内联委托可覆盖ConnectionString、DisableHealthChecks、DisableTracing、DisableAutoActivation通过ConfigureConfigurationOptions依次绑定默认节、命名节再调用configureOptions内联委托。AppHost 编排端集成Aspire.Hosting.Redis在 Aspire 的标准开发体验中Redis 服务器通常由 AppHost 统一编排消费者项目通过引用自动获得连接配置。安装宿主集成包在 AppHost 项目中安装Aspire.Hosting.Redisdotnet add package Aspire.Hosting.Redis注册 Redis 资源并建立引用在 AppHost 的AppHost.cs中注册 Redis 服务器资源并通过WithReference将其连接信息注入到目标服务项目var redis builder.AddRedis(cache); var myService builder.AddProjectProjects.MyService() .WithReference(redis);WithReference会在MyService项目中配置一个名为cache的连接连接名取自AddRedis的参数。随后在MyService的Program.cs中直接消费builder.AddRedisDistributedCache(cache);AddRedisDistributedCache会通过ConnectionStrings:cache找到 AppHost 注入的连接字符串完成与编排资源的对接。若需要本地开发时先运行 Redis 容器也可直接使用AddRedis(cache)让 AppHost 以容器方式启动 Redis。健康检查、日志与遥测组件默认开启的三项可观测性能力均可通过StackExchangeRedisSettings关闭健康检查Health Check默认注册AddRedis健康检查名称StackExchange.Redis。源码AspireRedisExtensions.cs将连接工厂以闭包形式捕获由健康检查在探测时调用并处理异常避免启动阶段因 Redis 不可用而崩溃。可通过DisableHealthChecks true关闭。日志Logging自动配置ILoggerFactory供ConfigurationOptions.LoggerFactory使用并声明Microsoft.Extensions.Caching.StackExchangeRedis的日志级别配置项。遥测Telemetry基于 OpenTelemetry 的 StackExchange.Redis 插桩。值得注意的细节是源码注释AspireRedisExtensions.cs说明组件刻意不调用AddRedisInstrumentation()因为那样会导致TelemetryHostedService在启动时通过 DI 解析并连接IConnectionMultiplexer——若 Redis 不可用会引发应用崩溃。组件改为手动注册ActivitySource与StackExchangeRedisInstrumentation并在CreateConnection时把新连接AddConnection到插桩对象既保留追踪能力又避免启动强依赖。Aspire 专属的默认重试行为ConfigurationOptionsFactory中内置了AspireDefaultOptionsProviderAspireRedisExtensions.cs将AbortOnConnectFail覆盖为false连接失败时不立即中止而是允许重试——即使在本机开发环境 Redis 尚未就绪时应用也能继续运行并等待重连这是 Aspire 相比原生 StackExchange.Redis 默认行为的重要差异。测试验证与正确性保障组件配套的测试项目 tests/Aspire.StackExchange.Redis.DistributedCaching.Tests 从三个角度保障行为正确AspireRedisDistributedCacheExtensionsTests.cs验证AddRedisDistributedCache与AddRedisClientBuilder(...).WithDistributedCache()均能正确解析出RedisCache类型的IDistributedCache基于 Testcontainers 验证InstanceName键前缀生效写入的 Redis 键以myCache开头验证多个键控缓存互不干扰、数据隔离正确。DistributedCacheConformanceTests.cs对IDistributedCache标准语义做一致性conformance验证。StackExchangeRedisDistributedCachingPublicApiTests.cs锁定公开 API 表面对应 api/Aspire.StackExchange.Redis.DistributedCaching.cs防止公共接口意外变更。与其他 Aspire 组件的配套使用本组件与以下仓库资源天然互补Aspire.StackExchange.Redis提供IConnectionMultiplexer客户端与全部设置/委托类型本组件是其功能的上层封装Aspire.Hosting.RedisAppHost 端 Redis 资源编排负责容器启动与连接注入Aspire Dashboard通过健康检查与遥测数据在 Dashboard 中集中呈现 Redis 实例状态与调用链路。此外若需要更强的缓存能力可关注仓库中基于本组件的 Aspire.StackExchange.Redis.OutputCaching 等变体组件但本文不展开。小结Aspire.StackExchange.Redis.DistributedCaching让在 Aspire 应用里用 Redis 做分布式缓存变成一行注册AddRedisDistributedCache自动完成连接复用、重试、健康检查、日志与遥测的装配。三种配置途径连接字符串 / 配置提供程序 / 内联委托覆盖了从本地开发到生产环境的全部场景Keyed 模式支持多缓存实例隔离AppHost 端的AddRedisWithReference则提供了声明式的编排体验。理解其底层实现——IConnectionMultiplexer单例注册、ConfigurationOptionsFactory的连接字符串解析、AspireDefaultOptionsProvider的重试默认值——有助于在遇到连接、追踪或健康检查问题时快速定位原因。注Redis 是 Redis Ltd. 的注册商标其相关权利归 Redis Ltd. 所有。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考