Aspire.StackExchange.Redis 集成组件在 .NET Aspire 中为应用注册 Redis 连接、健康检查与遥测【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire导读本文围绕 .NET Aspire 的Aspire.StackExchange.Redis组件讲解如何在消费端应用中把 Redis 的IConnectionMultiplexer注册进依赖注入DI容器并自动启用健康检查、日志与 OpenTelemetry 分布式追踪同时结合Aspire.Hosting.Redis托管集成介绍如何在 AppHost 中编排 Redis 容器并通过WithReference把连接传递给下游服务。读完本文你将掌握连接字符串、配置提供程序、内联委托三种配置方式以及多实例keyed注册、自动激活与自定义默认选项等进阶用法。组件源码位于 src/Components/Aspire.StackExchange.Redis托管集成为 src/Aspire.Hosting.Redis。组件概览与工作原理Aspire.StackExchange.Redis组件做的事情可以一句话概括在 DI 容器中注册一个单例的IConnectionMultiplexer用于连接 Redis 服务器并顺带启用相应的健康检查、日志和遥测参见 README.md。从实现上看其核心是 AspireRedisExtensions.cs 中的AddRedisClient扩展方法。该方法是IHostApplicationBuilder的扩展整体注册流程AddRedisClient 私有实现大致如下从配置节Aspire:StackExchange:Redis默认节名定义见 AspireRedisExtensions.cs读取StackExchangeRedisSettings若ConnectionStrings配置节中存在同名连接字符串则覆盖设置中的ConnectionString通过自定义的ConfigurationOptionsFactory解析ConfigurationOptions最终调用ConnectionMultiplexer.Connect(...)建立连接CreateConnection按开关注册 OpenTelemetry 追踪与 Redis 健康检查默认启用自动激活auto activation在启动时即建立连接避免首次从 DI 取用时阻塞线程。组件暴露的公开 API 可通过 api/Aspire.StackExchange.Redis.cs 一览无余AddRedisClient/AddRedisClientBuilder非 keyed与AddKeyedRedisClient/AddKeyedRedisClientBuilderkeyed四组入口加上StackExchangeRedisSettings与AspireRedisClientBuilder两个类型。快速开始前置条件使用本组件前你需要一个可用的 Redis 服务器并知道用于连接的服务端主机名hostname。安装 NuGet 包在消费端项目即使用 Redis 的业务项目中安装组件包dotnet add package Aspire.StackExchange.Redis注册并注入 IConnectionMultiplexer在应用的Program.cs或AppHost.cs文件中调用AddRedisClient扩展方法传入连接名称参数即可在 DI 容器中注册一个IConnectionMultiplexerbuilder.AddRedisClient(cache);之后便可以在任何地方通过构造函数注入IConnectionMultiplexer。例如在一个 Web API 控制器中private readonly IConnectionMultiplexer _cache; public ProductsController(IConnectionMultiplexer cache) { _cache cache; }拿到IConnectionMultiplexer后就可以调用GetDatabase()等 StackExchange.Redis API 执行 Redis 命令。关于IConnectionMultiplexer的详细用法可查阅 StackExchange.Redis 官方文档Basics 章节。连接的建立时机自动激活值得一提的实现细节是组件在注册单例连接后默认调用builder.Services.ActivateSingletonIConnectionMultiplexer()立即激活连接AspireRedisExtensions.cs。也就是说连接在应用启动阶段就会建立而不是等到第一次从 DI 解析时才建立从而避免首次请求阻塞工作线程。如果你不希望启动即连接可以通过StackExchangeRedisSettings.DisableAutoActivation关闭该行为。配置 Redis 连接组件提供多种配置途径可根据项目约定按需选用。需要特别说明无论使用哪种方式至少需要提供一个主机名才能建立连接README.md。如果解析出的ConfigurationOptions没有端点GetConfigurationOptions会抛出InvalidOperationException提示检查ConnectionStrings:{connectionName}或Aspire:StackExchange:Redis:ConnectionString配置键AspireRedisExtensions.cs。方式一使用连接字符串当连接字符串来自配置的ConnectionStrings节时把该节中的键名传给AddRedisClientbuilder.AddRedisClient(myRedisConnectionName);对应的appsettings.json{ ConnectionStrings: { myRedisConnectionName: localhost:6379 } }连接字符串的格式化规则遵循 StackExchange.Redis 的 Basic Configuration Settings 语法。例如带密码与数据库编号的写法形如host:port,passwordxxx,defaultDatabase0。实现上连接字符串会优先覆盖同名配置节中的ConnectionString设置AspireRedisExtensions.cs随后在ConfigurationOptionsFactory.CreateInstance中通过ConfigurationOptions.Parse(connectionString)解析成ConfigurationOptionsAspireRedisExtensions.cs。方式二使用配置提供程序Microsoft.Extensions.Configuration组件支持标准配置体系通过Aspire:StackExchange:Redis配置键加载StackExchangeRedisSettings和ConfigurationOptions。下面是一个appsettings.json示例配置了连接超时、重连次数并关闭健康检查、保留追踪{ Aspire: { StackExchange: { Redis: { ConfigurationOptions: { ConnectTimeout: 3000, ConnectRetry: 2 }, DisableHealthChecks: true, DisableTracing: false } } } }配置节中的可用设置项结合 StackExchangeRedisSettings.cs 与 ConfigurationSchema.json后者也是 VS 等工具用于配置智能提示的 JSON Schema 来源顶层设置项如下配置键类型默认值说明ConnectionStringstring无连接 Redis 的逗号分隔配置字符串也可通过ConnectionStrings节提供DisableHealthChecksboolfalse是否禁用 Redis 健康检查DisableTracingboolfalse是否禁用 OpenTelemetry 追踪DisableAutoActivationbooltrue源码中字段默认值为true即默认不自动激活的开关本身注意该字段语义是禁用自动激活见下方说明是否禁用启动时自动激活连接说明DisableAutoActivation的语义为禁用自动激活。当它为false时连接在启动阶段即被激活。在 StackExchangeRedisSettings.cs 中该属性默认值为true而在 AspireRedisExtensions.cs 中激活逻辑的判断条件是if (!settings.DisableAutoActivation)。实际发布版本的默认行为以 NuGet 包为准若需明确控制建议在配置或委托中显式设置。ConfigurationOptions 常用项速查ConfigurationOptions直接透传 StackExchange.Redis 的连接选项ConfigurationSchema.json中给出了完整的字段清单。这里列出最常用的几个及默认行为选项类型默认行为/说明ConnectTimeoutinteger连接超时毫秒默认 5 秒除非SyncTimeout更高ConnectRetryinteger初始连接循环在无服务器及时响应时的重试次数SyncTimeoutinteger同步操作超时毫秒默认 5 秒AsyncTimeoutinteger异步操作超时毫秒默认跟随SyncTimeoutAbortOnConnectFailboolean是否在连接/配置超时时显式抛出TimeoutExceptionAspire 组件将其强制设为false见下文AllowAdminboolean是否允许管理员操作默认关闭DefaultDatabaseinteger未指定参数时GetDatabase()使用的默认数据库编号Password/Userstring认证密码 / 用户名Ssl/SslHost/SslProtocolsboolean / string / enumTLS 加密开关、校验主机名、允许的协议ProtocolenumResp2/Resp3Redis 通信协议ProxyenumNone/Twemproxy/Envoyproxy使用的代理类型ResolveDnsboolean连接前是否通过 DNS 解析端点KeepAliveinteger保活 ping 间隔秒-1 时默认 60 秒ConfigCheckSecondsinteger配置检查间隔秒默认每分钟HeartbeatIntervalstringTimeSpan心跳间隔用于评估消息超时与连接状态ClientName/LibraryNamestring客户端名 /CLIENT SETINFO lib-name值默认SE.RedisChannelPrefixobject通道自动编解码前缀含UseImplicitAutoPatternHighIntegrityboolean是否对每条命令做严格协议校验有额外开销IncludeDetailInExceptionsboolean异常是否包含键名等可识别细节TieBreakerstring主节点选择用的 tie-breaker 键ServiceNamestring通过 sentinel 解析服务时使用的服务名CheckCertificateRevocationboolean认证时是否检查证书吊销列表这些选项与 StackExchange.Redis 官方ConfigurationOptions一一对应更多语义可参阅 StackExchange.Redis 的 Configuration Options 文档。方式三使用内联委托inline delegates也可以在代码中通过委托直接设置部分或全部选项。用ActionStackExchangeRedisSettings configureSettings委托修改组件设置例如从代码中禁用健康检查builder.AddRedisClient(cache, settings settings.DisableHealthChecks true);用ActionConfigurationOptions configureOptions委托修改ConfigurationOptions例如设置连接超时builder.AddRedisClient(cache, configureOptions: options options.ConnectTimeout 3000);两个委托可以同时使用。从实现看configureSettings会在配置绑定之后、注册服务之前被调用AspireRedisExtensions.csconfigureOptions则在ConfigurationOptions配置回调中执行AspireRedisExtensions.cs且配置绑定先于委托执行因此内联委托拥有最高的优先级适合覆盖环境特定配置。AppHost 托管集成编排 Redis 资源以上内容面向消费 Redis 的业务项目。若要在解决方案中真正编排一个 Redis 容器还需要在 AppHost 项目中安装托管集成包dotnet add package Aspire.Hosting.Redis也可以使用 Aspire CLI 添加aspire add Aspire.Hosting.Redis参见 src/Aspire.Hosting.Redis/README.md。然后在AppHost的Program.cs中注册 Redis 服务器资源并让下游服务引用它var redis builder.AddRedis(cache); var myService builder.AddProjectProjects.MyService() .WithReference(redis);WithReference会在MyService项目中生成一个名为cache的连接。随后在MyService的Program.cs中用同一个名字消费该连接builder.AddRedisClient(cache);这样就完成了AppHost 编排容器 → 自动注入连接字符串 → 消费端注册 IConnectionMultiplexer的完整链路。AddRedis 背后的容器编排细节从源码看AddRedisRedisBuilderExtensions.cs会创建一个RedisResource容器资源并完成以下编排绑定容器内部端口 6379 到宿主端口port参数可空为空时由 Aspire 自动分配使用 RedisContainerImageTags.cs 中定义的官方镜像与标签若未提供密码参数会自动生成一个随机密码CreateDefaultPasswordParameter并以--requirepass $REDIS_PASSWORD方式传给redis-serverRedisBuilderExtensions.cs。源码注释特别提到StackExchange.Redis 不支持包含逗号的密码因此生成逻辑会规避该问题注册内置健康检查AddHealthChecks().AddRedis(...)配合WaitFor可让下游资源等待 Redis 就绪后再启动支持持久化--save interval keysChangedThreshold与模块加载--loadmodule注解在启用 TLS 证书配置时会追加--tls-cert-file、--tls-key-file等参数并分配 6380 端口作为 TLS 端点见 RedisBuilderExtensions.cs。连接属性与连接字符串格式RedisResourceRedisResource.cs实现了IResourceWithConnectionString对外暴露以下连接属性属性名说明HostRedis 服务器主机名或 IPPortRedis 服务器监听端口Password认证密码Uri连接 URI格式为redis://:{Password}{Host}:{Port}Aspire 会把每个属性以[资源名]_[属性名]的环境变量形式暴露给消费方例如名为cache的资源的Uri属性对应环境变量CACHE_URIsrc/Aspire.Hosting.Redis/README.md。生成的连接字符串形如host:port,passwordxxx若启用了 TLS 会追加,ssltrueURI 表达式则在启用 TLS 时使用rediss://schemeRedisResource.cs。可视化与管理工具Aspire.Hosting.Redis还提供了两个可选的管理 UI 扩展WithRedisCommander()为 Redis 资源附加 Redis Commander 容器默认容器名rediscommanderHTTP 端口 8081自动收集所有 Redis 实例并通过REDIS_HOSTS环境变量注入RedisBuilderExtensions.csWithRedisInsight()附加 Redis Insight 容器默认容器名redisinsightHTTP 端口 5540通过RI_REDIS_HOST{n}、RI_REDIS_PORT{n}等环境变量注入各实例信息RedisBuilderExtensions.cs。这两个工具容器均被标记为ExcludeFromManifest()即只用于本地开发调试不会进入部署清单。高级主题多实例keyed注册与共享默认值连接多个 Redis 实例一个应用中可能需要连接多个 Redis例如缓存与 Session 分离。组件提供了 keyed 注册入口builder.AddKeyedRedisClient(cache); builder.AddKeyedRedisClient(session);AddKeyedRedisClient会以name作为服务的ServiceKey注册一个 keyed 单例IConnectionMultiplexer并同时用它去ConnectionStrings节取连接字符串配置节则从Aspire:StackExchange:Redis:{name}读取AspireRedisExtensions.cs。取用时var cache services.GetRequiredKeyedServiceIConnectionMultiplexer(cache);keyed 模式下健康检查的名称也会带上连接名形如StackExchange.Redis_cache便于在健康检查面板中区分AspireRedisExtensions.cs。Aspire 对 StackExchange.Redis 默认选项的调整组件通过自定义AspireDefaultOptionsProvider覆盖了库默认行为将AbortOnConnectFail设为falseAspireRedisExtensions.cs。注释表明这是为了让连接在本地开发等场景下失败后仍能重试而不是立即中止。这意味着应用启动时若 Redis 暂时不可用连接会保持重试而非立刻抛出异常。遥测的实现细节在追踪方面组件刻意没有调用AddRedisInstrumentation()而是手动注册ActivitySource并调用ConfigureRedisInstrumentation与AddInstrumentationAspireRedisExtensions.cs。源码注释解释了原因直接调用AddRedisInstrumentation()会让TelemetryHostedService在启动时通过 DI 解析并连接IConnectionMultiplexer一旦 Redis 不可用就可能导致应用崩溃。改用手动注册后连接建立时通过StackExchangeRedisInstrumentation.AddConnection(connection)完成注册CreateConnection既保证了追踪能力又避免启动期崩溃。从设置到连接的解析链当连接字符串存在时ConfigurationOptionsFactory.CreateInstance使用ConfigurationOptions.Parse(connectionString)从零解析出选项对象而非在已有对象上修改这正是它继承OptionsFactoryConfigurationOptions并重写CreateInstance的原因其它开发者也仍可通过标准的Configure/PostConfigure/Validate扩展选项AspireRedisExtensions.cs。此外若未显式设置LoggerFactory组件会把 DI 中的ILoggerFactory注入到ConfigurationOptions保证连接日志与宿主日志体系打通AspireRedisExtensions.cs。验证与测试该组件的测试位于 tests/Aspire.StackExchange.Redis.Tests如AspireRedisExtensionsTests.cs、StackExchangeRedisPublicApiTests.cs、ConformanceTests.cs。其中StackExchangeRedisPublicApiTests对照 api/Aspire.StackExchange.Redis.cs 校验公开 API 面ConformanceTests用于验证组件在配置绑定、健康检查与遥测注册上的约定行为。读者若需确认某配置项的实际效果可在这些测试中查找对应断言。常见问题与注意事项必须提供主机名无论走连接字符串、配置节还是内联委托最终解析出的ConfigurationOptions至少要有一个端点否则组件会在启动时抛出异常。连接字符串与配置节的关系ConnectionStrings:{connectionName}中的值会覆盖Aspire:StackExchange:Redis:ConnectionString中的同名设置configureSettings委托又覆盖前两者优先级从低到高为配置节 → 连接字符串 → 内联委托。密码中不要使用逗号StackExchange.Redis 的连接字符串以逗号分隔选项因此密码含逗号会导致解析错误Aspire 托管集成生成的随机密码已规避此问题但自定义密码时需留意。启动期连接行为默认自动激活会在启动时建立连接若 Redis 启动较慢或不可达请结合DisableAutoActivation、ConnectTimeout、ConnectRetry与AbortOnConnectFailfalse的默认策略综合考虑必要时配合 AppHost 的WaitFor使用。TLS 场景托管集成启用 TLS 后连接字符串会自动追加,ssltrueURI 使用rediss://客户端无需额外配置即可建立加密连接。延伸阅读组件源码与配置 Schemasrc/Components/Aspire.StackExchange.Redis托管集成源码src/Aspire.Hosting.Redis组件测试tests/Aspire.StackExchange.Redis.Tests其他 Aspire 组件的说明文档可参考 src/Components 目录下各组件各自的 README【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
