尧图网页设计 
Aspire MongoDB.Driver 组件实战指南从 IMongoClient 注册到连接编排与健康检查【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本篇指南围绕 .NET Aspire 仓库中Aspire.MongoDB.Driver组件的官方文档src/Components/Aspire.MongoDB.Driver/README.md展开结合其底层源码与测试用例系统讲解如何把 MongoDB.Driver 官方客户端接入 Aspire 的依赖注入DI容器如何通过连接字符串、配置节与内联委托三种方式配置连接以及如何在 AppHost 中配合Aspire.Hosting.MongoDB完成 MongoDB 资源的建模、编排与消费。读完本文你将能够在一个 Aspire 解决方案中从零打通AppHost 定义 MongoDB 资源 → 服务项目消费 IMongoClient/IMongoDatabase → 健康检查与分布式追踪自动生效的完整链路。组件概述它到底帮你做了什么Aspire.MongoDB.Driver是 Aspire 组件生态中的数据库客户端组件之一。其核心职责一句话可以概括在 DI 容器中注册IMongoClient以及派生出的IMongoDatabase用于连接 MongoDB 数据库并且把连接管理、配置绑定、健康检查和 OpenTelemetry 追踪这些基础设施琐事从你的业务代码中剥离出去。从源码看该组件的入口是 AspireMongoDBDriverExtensions.cs 中定义的扩展方法AddMongoDBClient。调用它之后组件会完成四件事注册客户端以AddSingleton或键控AddKeyedSingleton方式注册IMongoClient注册数据库当连接字符串中携带数据库名mongodb://server:port/test中的test时额外注册对应的IMongoDatabase接入追踪默认启用基于MongoDB.Driver.Core.Extensions.DiagnosticSources的 OpenTelemetry 追踪注册健康检查默认注册名为MongoDB.Driver的健康检查。从源码结构看AddMongoDatabaseAspireMongoDBDriverExtensions.cs只有在连接字符串能解析出数据库名时才会注册IMongoDatabase如果连接字符串不带数据库名如mongodb://localhost:27017则只会注册IMongoClient这与测试 AspireMongoDBDriverExtensionsTests.cs 中是否注册数据库的断言逻辑完全一致。快速开始安装与前置条件前置条件使用该组件前你需要准备一个可访问的 MongoDB 数据库实例本地安装、Docker/Testcontainers 容器或云服务均可对应的 MongoDB 连接字符串例如mongodb://server:port/test。安装 NuGet 包在需要使用 MongoDB 客户端的业务项目而非 AppHost中执行dotnet add package Aspire.MongoDB.Driver基本用法注册客户端并从 DI 解析在 AppHost 或服务宿主中注册在项目的_AppHost.cs或任意IHostApplicationBuilder构建现场中调用AddMongoDBClient扩展方法注册一个IMongoClient该方法接受一个连接名称connection name参数builder.AddMongoDBClient(mongodb);这个连接名称不是随便起的——它会被用作从ConnectionStrings配置节查找连接字符串的键下文详解。通过构造函数注入消费注册完成后即可像使用任何 DI 服务一样获取IMongoClient。例如在 Web API 控制器中通过构造函数注入private readonly IMongoClient _client; public ProductsController(IMongoClient client) { _client client; }由于IMongoClient以 Singleton 生命周期注册见 ConformanceTests.cs 的ServiceLifetime ServiceLifetime.Singleton它会在整个应用生命周期内被复用符合 MongoDB 官方驱动对客户端实例长生命周期、全局复用的推荐用法。键控注册同时连接多个 MongoDB 实例除了基础版AddMongoDBClient组件还提供了AddKeyedMongoDBClient用于在同一个应用中注册多个不同的 MongoDB 连接// 非键控默认连接 builder.AddMongoDBClient(mongodb1); // 键控以名称作为 ServiceKey builder.AddKeyedMongoDBClient(mongodb2); builder.AddKeyedMongoDBClient(mongodb3);键控注册时name参数同时充当ServiceDescriptor.ServiceKey与连接字符串的查找键。消费方需要使用GetRequiredKeyedServiceIMongoClient(mongodb2)来获取对应的实例。测试 CanAddMultipleKeyedServices 验证了同一应用内同时注册多个 MongoDB 连接且彼此隔离这一场景每个连接解析出的IMongoDatabase的DatabaseName各不相同。配置三种方式满足不同项目约定组件支持多种配置途径优先级从源码 GetMongoDBSettings 可以确认先加载Aspire:MongoDB:Driver配置节再叠加ConnectionStrings节中对应名称的连接字符串最后以内联委托若提供收尾覆盖。方式一使用 ConnectionStrings 配置节最直接的方式把连接字符串放进ConnectionStrings配置节键名与调用AddMongoDBClient时传入的连接名称一致builder.AddMongoDBClient(myConnection);对应的配置文件如appsettings.json{ ConnectionStrings: { myConnection: mongodb://server:port/test } }组件从源码实现看会优先检查ConnectionStrings节中是否存在该名称存在即作为最终ConnectionString使用AspireMongoDBDriverExtensions.cs。关于连接字符串的格式细节如authSource、replicaSet等选项可参考 MongoDB 官方的 Connection String 文档典型形式包括无认证mongodb://localhost:27017/mydatabase带认证mongodb://admin:passlocalhost:27017/mydatabase?authSourceadminauthMechanismSCRAM-SHA-256测试 AspireMongoDBDriverExtensionsTests.cs 专门覆盖了这两类连接字符串的解析认证信息用户名、认证库、认证机制会被正确映射到MongoClientSettings.Credential。方式二使用 Aspire:MongoDB:Driver 配置节组件遵循 .NET 标准配置体系Microsoft.Extensions.Configuration从Aspire:MongoDB:Driver键读取MongoDBSettings。示例appsettings.json{ Aspire: { MongoDB: { Driver: { ConnectionString: mongodb://server:port/test, DisableHealthChecks: false, HealthCheckTimeout: 10000, DisableTracing: false } } } }该配置节的结构由 ConfigurationSchema.json 明确定义包含四个属性对应 MongoDBSettings.cs 中的字段配置键类型默认值说明ConnectionStringstring无要连接的 MongoDB 连接字符串DisableHealthChecksbooleanfalse是否禁用 MongoDB 健康检查HealthCheckTimeoutinteger无不设超时健康检查超时时间单位毫秒DisableTracingbooleanfalse是否禁用 OpenTelemetry 追踪组件同时支持具名子配置节当使用键控注册AddKeyedMongoDBClient(name)时会读取Aspire:MongoDB:Driver:{name}子节见扩展方法 XML 注释AspireMongoDBDriverExtensions.cs方便为每个具名连接单独配置。配置校验有据可查Conformance 测试 InvalidJsonToErrorMessage 验证了类型错误会被拦截例如把DisableHealthChecks配成字符串true会报错Value is string but should be boolean把HealthCheckTimeout配成字符串会报错Value is string but should be integer。方式三使用内联委托你也可以通过ActionMongoDBSettings configureSettings委托在代码中直接设置部分或全部选项builder.AddMongoDBClient(mongodb, settings settings.ConnectionString mongodb://server:port/test);此外两个扩展方法还支持第二个可选委托ActionMongoClientSettings configureClientSettings用于进一步定制 MongoDB 驱动的底层客户端设置如认证、连接池、读写偏好等builder.AddMongoDBClient( mongodb, settings settings.ConnectionString mongodb://server:port/test, clientSettings clientSettings.ServerSelectionTimeout TimeSpan.FromSeconds(5));从源码 CreateMongoClient 可以看到该委托的执行时机连接字符串已被解析为MongoClientSettings之后、MongoClient实例构造之前。源码还揭示了几处隐形增强默认开启诊断追踪ClusterConfigurator会订阅DiagnosticsActivityEventSubscriber自动接入日志LoggingSettings默认绑定应用现有的ILoggerFactory客户端标识标注向 MongoDB 服务器上报的LibraryInfo会追加|aspire与组件版本号便于在服务器端辨识流量来源。三条配置途径的优先级从低到高Aspire:MongoDB:Driver配置节 →ConnectionStrings节 → 内联委托。即内联委托拥有最终决定权。AppHost 扩展在编排层建模 MongoDB 资源以上的Aspire.MongoDB.Driver解决的是客户端如何连接而数据库资源如何被定义、启动和注入连接信息则由Aspire.Hosting.MongoDB托管集成负责其官方文档见 src/Aspire.Hosting.MongoDB/README.md。安装托管集成包在AppHost 项目中安装dotnet add package Aspire.Hosting.MongoDB注册资源并建立引用在 AppHost 的_AppHost.cs中注册一个 MongoDB 服务器及数据库并通过WithReference把它连接到业务服务var mongodb builder.AddMongoDB(mongodb).AddDatabase(mydatabase); var myService builder.AddProjectProjects.MyService() .WithReference(mongodb);WithReference会在MyService项目中生成一个名为mongodb的连接配置连接名称取自AddMongoDB(mongodb)的资源名。随后在MyService的Program.cs中即可消费builder.AddMongoDBClient(mongodb);这一行会从ConnectionStrings配置节读取由 AppHost 自动注入的mongodb连接字符串——正是前文方式一的典型应用场景。两端由此完成对接AppHost 负责造资源、给连接信息业务项目负责读配置、建客户端。通过连接属性理解注入机制WithReference注入的内容可以进一步通过连接属性Connection Properties理解。Aspire 会把 MongoDB 资源的各项属性以环境变量的形式暴露给消费项目命名规则为[资源名]_[属性名]例如资源db1的Uri属性变成DB1_URI。MongoDB 服务器资源暴露的连接属性包括属性名说明HostMongoDB 服务器的主机名或 IPPort服务器监听端口Username认证用户名Password认证密码配置了密码参数时可用AuthenticationDatabase认证数据库配置了密码参数时可用AuthenticationMechanism认证机制配置了密码参数时可用Uri连接 URI格式为mongodb://{Username}:{Password}{Host}:{Port}/?authSource{AuthenticationDatabase}authMechanism{AuthenticationMechanism}在服务器属性之上数据库资源额外增加DatabaseName数据库名。完整的连接属性说明见 Aspire.Hosting.MongoDB/README.md。进阶副本集Replica Set编排Aspire.Hosting.MongoDB还支持把多个 MongoDB 实例编排成逻辑上的副本集从而启用事务transactions与变更流change streamsvar mongo1 builder.AddMongoDB(mongo-1); var mongo2 builder.AddMongoDB(mongo-2); var mongo3 builder.AddMongoDB(mongo-3); var replicaSet builder.AddMongoDBReplicaSet(rs0) .WithMember(mongo1) .WithMember(mongo2) .WithMember(mongo3); var myService builder.AddProjectProjects.MyService() .WithReference(replicaSet) .WaitFor(replicaSet);副本集对外暴露的连接属性与单机不同它没有单一的Host/Port客户端通过Uri中携带的种子列表seed list发现成员。Uri格式为mongodb://{Username}:{Password}{Host1}:{Port1},{Host2}:{Port2}/?replicaSet{ReplicaSetName}authSource{AuthenticationDatabase}authMechanism{AuthenticationMechanism}需要特别留意官方文档标注的两个约束见 Aspire.Hosting.MongoDB/README.md副本集仅本地可用副本集由 AppHost 在本地初始化部署publish 模式时无人执行该步骤因此AddMongoDBReplicaSet在 publish 模式下会抛异常成员共享一套凭据用户名/密码应传给AddMongoDBReplicaSet而非单个成员给不同成员传不同凭据会被拒绝同时 MongoDB 只在空数据目录上应用初始凭据若某成员服务器带旧数据卷加入副本集需从空卷启动或把该服务器既有的密码参数传入副本集。如果只是需要事务和变更流而不需要冗余单个成员即可满足副本集最多 50 个成员前 7 个参与选举投票其余以非投票成员身份加入但仍保留完整数据副本。TLS 注意事项MongoDB 服务器在存在 HTTPS/TLS 证书时默认使用 ASP.NET Core 开发者证书会自动启用 TLS。连接字符串会通过tlstrue标志反映这一点消费者自动感知。两个典型边界情况值得注意Aspire.Hosting.MongoDB/README.md开发者证书只签发给localhost本机运行的消费者可顺利通过校验但容器内运行的消费者通过容器网络中的资源名访问服务器该名称不在证书覆盖范围内TLS 握手会因主机名校验失败此时需要放宽主机名校验单机服务器可用WithoutHttpsCertificate()完全退出 TLS但副本集成员必须提供 TLS因为其分割视野split-horizon寻址依赖入站连接的 SNI无 TLS 的成员会以明确错误信息初始化失败。健康检查与可观测性开箱即得的运维能力健康检查组件默认注册名为MongoDB.Driver的健康检查键控注册时为MongoDB.Driver_{connectionName}实现基于AspNetCore.HealthChecks.MongoDb包。相关行为见源码 AddHealthCheck当DisableHealthChecks为true或未提供连接字符串时跳过注册HealthCheckTimeout大于 0 时以毫秒为单位转换为健康检查超时时间TimeSpan.FromMilliseconds。测试 AspireMongoDBDriverExtensionsTests.cs 验证了四种组合开启时健康检查出现在报告中键名分别为MongoDB.Driver与MongoDB.Driver_mongodb禁用时HealthCheckService甚至不会被注册。分布式追踪与日志组件默认接入 OpenTelemetry 追踪Activity 源为MongoDB.Driver.Core.Extensions.DiagnosticSources源码常量ActivityNameSourceAspireMongoDBDriverExtensions.cs。DisableTracing置为true可关闭。Conformance 测试 ConformanceTests.cs 通过ListDatabases触发实际数据库操作来验证追踪是否产生。日志方面组件要求以下 MongoDB 驱动日志类别可达见 ConformanceTests.cs 与 ConfigurationSchema.json 中的logLevel定义MongoDB根类别MongoDB.CommandMongoDB.ConnectionMongoDB.InternalMongoDB.SDAM服务器发现与监控MongoDB.ServerSelection服务器选择这些类别可在Logging:LogLevel配置节中按需调整日志级别。注意该组件当前未实现 MetricsConformance 测试中SetMetrics直接抛出NotImplementedExceptionConformanceTests.cs可观测性能力聚焦在追踪与日志两条线上。运行时行为细节值得注意的源码事实连接字符串缺失会抛异常ValidateSettings会调用ConnectionStringValidation.ValidateConnectionStringAspireMongoDBDriverExtensions.cs在创建客户端时若缺少连接字符串将抛出InvalidOperationException提示信息会带出连接名称与配置节路径便于定位问题。IMongoDatabase是连接字符串有库名才注册连接字符串中的库名会被MongoUrl.Create解析只有解析出非空数据库名时才注册IMongoDatabase单例AspireMongoDBDriverExtensions.cs。测试中mongodb://localhost:27017/mydatabase能解析出IMongoDatabase而mongodb://localhost:27017则不能。组件只做客户端集成不负责启动数据库本地开发时数据库实例由 AppHost 中的AddMongoDB通过容器编排拉起Aspire.MongoDB.Driver本身不包含任何容器或服务器逻辑两者的职责边界清晰。更多资源组件与托管集成的官方文档分别为 src/Components/Aspire.MongoDB.Driver/README.md 与 src/Aspire.Hosting.MongoDB/README.md组件公共 API 一览见 api/Aspire.MongoDB.Driver.cs配置 Schema 见 ConfigurationSchema.json完整测试套件位于 tests/Aspire.MongoDB.Driver.Tests/含扩展方法测试、Conformance 测试与基于 Testcontainers 的MongoDbContainerFixture可据此了解组件的全部契约行为。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Aspire MongoDB.Driver 组件实战指南：从 IMongoClient 注册到连接编排与健康检查
Aspire MongoDB.Driver 组件实战指南从 IMongoClient 注册到连接编排与健康检查【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本篇指南围绕 .NET Aspire 仓库中Aspire.MongoDB.Driver组件的官方文档src/Components/Aspire.MongoDB.Driver/README.md展开结合其底层源码与测试用例系统讲解如何把 MongoDB.Driver 官方客户端接入 Aspire 的依赖注入DI容器如何通过连接字符串、配置节与内联委托三种方式配置连接以及如何在 AppHost 中配合Aspire.Hosting.MongoDB完成 MongoDB 资源的建模、编排与消费。读完本文你将能够在一个 Aspire 解决方案中从零打通AppHost 定义 MongoDB 资源 → 服务项目消费 IMongoClient/IMongoDatabase → 健康检查与分布式追踪自动生效的完整链路。组件概述它到底帮你做了什么Aspire.MongoDB.Driver是 Aspire 组件生态中的数据库客户端组件之一。其核心职责一句话可以概括在 DI 容器中注册IMongoClient以及派生出的IMongoDatabase用于连接 MongoDB 数据库并且把连接管理、配置绑定、健康检查和 OpenTelemetry 追踪这些基础设施琐事从你的业务代码中剥离出去。从源码看该组件的入口是 AspireMongoDBDriverExtensions.cs 中定义的扩展方法AddMongoDBClient。调用它之后组件会完成四件事注册客户端以AddSingleton或键控AddKeyedSingleton方式注册IMongoClient注册数据库当连接字符串中携带数据库名mongodb://server:port/test中的test时额外注册对应的IMongoDatabase接入追踪默认启用基于MongoDB.Driver.Core.Extensions.DiagnosticSources的 OpenTelemetry 追踪注册健康检查默认注册名为MongoDB.Driver的健康检查。从源码结构看AddMongoDatabaseAspireMongoDBDriverExtensions.cs只有在连接字符串能解析出数据库名时才会注册IMongoDatabase如果连接字符串不带数据库名如mongodb://localhost:27017则只会注册IMongoClient这与测试 AspireMongoDBDriverExtensionsTests.cs 中是否注册数据库的断言逻辑完全一致。快速开始安装与前置条件前置条件使用该组件前你需要准备一个可访问的 MongoDB 数据库实例本地安装、Docker/Testcontainers 容器或云服务均可对应的 MongoDB 连接字符串例如mongodb://server:port/test。安装 NuGet 包在需要使用 MongoDB 客户端的业务项目而非 AppHost中执行dotnet add package Aspire.MongoDB.Driver基本用法注册客户端并从 DI 解析在 AppHost 或服务宿主中注册在项目的_AppHost.cs或任意IHostApplicationBuilder构建现场中调用AddMongoDBClient扩展方法注册一个IMongoClient该方法接受一个连接名称connection name参数builder.AddMongoDBClient(mongodb);这个连接名称不是随便起的——它会被用作从ConnectionStrings配置节查找连接字符串的键下文详解。通过构造函数注入消费注册完成后即可像使用任何 DI 服务一样获取IMongoClient。例如在 Web API 控制器中通过构造函数注入private readonly IMongoClient _client; public ProductsController(IMongoClient client) { _client client; }由于IMongoClient以 Singleton 生命周期注册见 ConformanceTests.cs 的ServiceLifetime ServiceLifetime.Singleton它会在整个应用生命周期内被复用符合 MongoDB 官方驱动对客户端实例长生命周期、全局复用的推荐用法。键控注册同时连接多个 MongoDB 实例除了基础版AddMongoDBClient组件还提供了AddKeyedMongoDBClient用于在同一个应用中注册多个不同的 MongoDB 连接// 非键控默认连接 builder.AddMongoDBClient(mongodb1); // 键控以名称作为 ServiceKey builder.AddKeyedMongoDBClient(mongodb2); builder.AddKeyedMongoDBClient(mongodb3);键控注册时name参数同时充当ServiceDescriptor.ServiceKey与连接字符串的查找键。消费方需要使用GetRequiredKeyedServiceIMongoClient(mongodb2)来获取对应的实例。测试 CanAddMultipleKeyedServices 验证了同一应用内同时注册多个 MongoDB 连接且彼此隔离这一场景每个连接解析出的IMongoDatabase的DatabaseName各不相同。配置三种方式满足不同项目约定组件支持多种配置途径优先级从源码 GetMongoDBSettings 可以确认先加载Aspire:MongoDB:Driver配置节再叠加ConnectionStrings节中对应名称的连接字符串最后以内联委托若提供收尾覆盖。方式一使用 ConnectionStrings 配置节最直接的方式把连接字符串放进ConnectionStrings配置节键名与调用AddMongoDBClient时传入的连接名称一致builder.AddMongoDBClient(myConnection);对应的配置文件如appsettings.json{ ConnectionStrings: { myConnection: mongodb://server:port/test } }组件从源码实现看会优先检查ConnectionStrings节中是否存在该名称存在即作为最终ConnectionString使用AspireMongoDBDriverExtensions.cs。关于连接字符串的格式细节如authSource、replicaSet等选项可参考 MongoDB 官方的 Connection String 文档典型形式包括无认证mongodb://localhost:27017/mydatabase带认证mongodb://admin:passlocalhost:27017/mydatabase?authSourceadminauthMechanismSCRAM-SHA-256测试 AspireMongoDBDriverExtensionsTests.cs 专门覆盖了这两类连接字符串的解析认证信息用户名、认证库、认证机制会被正确映射到MongoClientSettings.Credential。方式二使用 Aspire:MongoDB:Driver 配置节组件遵循 .NET 标准配置体系Microsoft.Extensions.Configuration从Aspire:MongoDB:Driver键读取MongoDBSettings。示例appsettings.json{ Aspire: { MongoDB: { Driver: { ConnectionString: mongodb://server:port/test, DisableHealthChecks: false, HealthCheckTimeout: 10000, DisableTracing: false } } } }该配置节的结构由 ConfigurationSchema.json 明确定义包含四个属性对应 MongoDBSettings.cs 中的字段配置键类型默认值说明ConnectionStringstring无要连接的 MongoDB 连接字符串DisableHealthChecksbooleanfalse是否禁用 MongoDB 健康检查HealthCheckTimeoutinteger无不设超时健康检查超时时间单位毫秒DisableTracingbooleanfalse是否禁用 OpenTelemetry 追踪组件同时支持具名子配置节当使用键控注册AddKeyedMongoDBClient(name)时会读取Aspire:MongoDB:Driver:{name}子节见扩展方法 XML 注释AspireMongoDBDriverExtensions.cs方便为每个具名连接单独配置。配置校验有据可查Conformance 测试 InvalidJsonToErrorMessage 验证了类型错误会被拦截例如把DisableHealthChecks配成字符串true会报错Value is string but should be boolean把HealthCheckTimeout配成字符串会报错Value is string but should be integer。方式三使用内联委托你也可以通过ActionMongoDBSettings configureSettings委托在代码中直接设置部分或全部选项builder.AddMongoDBClient(mongodb, settings settings.ConnectionString mongodb://server:port/test);此外两个扩展方法还支持第二个可选委托ActionMongoClientSettings configureClientSettings用于进一步定制 MongoDB 驱动的底层客户端设置如认证、连接池、读写偏好等builder.AddMongoDBClient( mongodb, settings settings.ConnectionString mongodb://server:port/test, clientSettings clientSettings.ServerSelectionTimeout TimeSpan.FromSeconds(5));从源码 CreateMongoClient 可以看到该委托的执行时机连接字符串已被解析为MongoClientSettings之后、MongoClient实例构造之前。源码还揭示了几处隐形增强默认开启诊断追踪ClusterConfigurator会订阅DiagnosticsActivityEventSubscriber自动接入日志LoggingSettings默认绑定应用现有的ILoggerFactory客户端标识标注向 MongoDB 服务器上报的LibraryInfo会追加|aspire与组件版本号便于在服务器端辨识流量来源。三条配置途径的优先级从低到高Aspire:MongoDB:Driver配置节 →ConnectionStrings节 → 内联委托。即内联委托拥有最终决定权。AppHost 扩展在编排层建模 MongoDB 资源以上的Aspire.MongoDB.Driver解决的是客户端如何连接而数据库资源如何被定义、启动和注入连接信息则由Aspire.Hosting.MongoDB托管集成负责其官方文档见 src/Aspire.Hosting.MongoDB/README.md。安装托管集成包在AppHost 项目中安装dotnet add package Aspire.Hosting.MongoDB注册资源并建立引用在 AppHost 的_AppHost.cs中注册一个 MongoDB 服务器及数据库并通过WithReference把它连接到业务服务var mongodb builder.AddMongoDB(mongodb).AddDatabase(mydatabase); var myService builder.AddProjectProjects.MyService() .WithReference(mongodb);WithReference会在MyService项目中生成一个名为mongodb的连接配置连接名称取自AddMongoDB(mongodb)的资源名。随后在MyService的Program.cs中即可消费builder.AddMongoDBClient(mongodb);这一行会从ConnectionStrings配置节读取由 AppHost 自动注入的mongodb连接字符串——正是前文方式一的典型应用场景。两端由此完成对接AppHost 负责造资源、给连接信息业务项目负责读配置、建客户端。通过连接属性理解注入机制WithReference注入的内容可以进一步通过连接属性Connection Properties理解。Aspire 会把 MongoDB 资源的各项属性以环境变量的形式暴露给消费项目命名规则为[资源名]_[属性名]例如资源db1的Uri属性变成DB1_URI。MongoDB 服务器资源暴露的连接属性包括属性名说明HostMongoDB 服务器的主机名或 IPPort服务器监听端口Username认证用户名Password认证密码配置了密码参数时可用AuthenticationDatabase认证数据库配置了密码参数时可用AuthenticationMechanism认证机制配置了密码参数时可用Uri连接 URI格式为mongodb://{Username}:{Password}{Host}:{Port}/?authSource{AuthenticationDatabase}authMechanism{AuthenticationMechanism}在服务器属性之上数据库资源额外增加DatabaseName数据库名。完整的连接属性说明见 Aspire.Hosting.MongoDB/README.md。进阶副本集Replica Set编排Aspire.Hosting.MongoDB还支持把多个 MongoDB 实例编排成逻辑上的副本集从而启用事务transactions与变更流change streamsvar mongo1 builder.AddMongoDB(mongo-1); var mongo2 builder.AddMongoDB(mongo-2); var mongo3 builder.AddMongoDB(mongo-3); var replicaSet builder.AddMongoDBReplicaSet(rs0) .WithMember(mongo1) .WithMember(mongo2) .WithMember(mongo3); var myService builder.AddProjectProjects.MyService() .WithReference(replicaSet) .WaitFor(replicaSet);副本集对外暴露的连接属性与单机不同它没有单一的Host/Port客户端通过Uri中携带的种子列表seed list发现成员。Uri格式为mongodb://{Username}:{Password}{Host1}:{Port1},{Host2}:{Port2}/?replicaSet{ReplicaSetName}authSource{AuthenticationDatabase}authMechanism{AuthenticationMechanism}需要特别留意官方文档标注的两个约束见 Aspire.Hosting.MongoDB/README.md副本集仅本地可用副本集由 AppHost 在本地初始化部署publish 模式时无人执行该步骤因此AddMongoDBReplicaSet在 publish 模式下会抛异常成员共享一套凭据用户名/密码应传给AddMongoDBReplicaSet而非单个成员给不同成员传不同凭据会被拒绝同时 MongoDB 只在空数据目录上应用初始凭据若某成员服务器带旧数据卷加入副本集需从空卷启动或把该服务器既有的密码参数传入副本集。如果只是需要事务和变更流而不需要冗余单个成员即可满足副本集最多 50 个成员前 7 个参与选举投票其余以非投票成员身份加入但仍保留完整数据副本。TLS 注意事项MongoDB 服务器在存在 HTTPS/TLS 证书时默认使用 ASP.NET Core 开发者证书会自动启用 TLS。连接字符串会通过tlstrue标志反映这一点消费者自动感知。两个典型边界情况值得注意Aspire.Hosting.MongoDB/README.md开发者证书只签发给localhost本机运行的消费者可顺利通过校验但容器内运行的消费者通过容器网络中的资源名访问服务器该名称不在证书覆盖范围内TLS 握手会因主机名校验失败此时需要放宽主机名校验单机服务器可用WithoutHttpsCertificate()完全退出 TLS但副本集成员必须提供 TLS因为其分割视野split-horizon寻址依赖入站连接的 SNI无 TLS 的成员会以明确错误信息初始化失败。健康检查与可观测性开箱即得的运维能力健康检查组件默认注册名为MongoDB.Driver的健康检查键控注册时为MongoDB.Driver_{connectionName}实现基于AspNetCore.HealthChecks.MongoDb包。相关行为见源码 AddHealthCheck当DisableHealthChecks为true或未提供连接字符串时跳过注册HealthCheckTimeout大于 0 时以毫秒为单位转换为健康检查超时时间TimeSpan.FromMilliseconds。测试 AspireMongoDBDriverExtensionsTests.cs 验证了四种组合开启时健康检查出现在报告中键名分别为MongoDB.Driver与MongoDB.Driver_mongodb禁用时HealthCheckService甚至不会被注册。分布式追踪与日志组件默认接入 OpenTelemetry 追踪Activity 源为MongoDB.Driver.Core.Extensions.DiagnosticSources源码常量ActivityNameSourceAspireMongoDBDriverExtensions.cs。DisableTracing置为true可关闭。Conformance 测试 ConformanceTests.cs 通过ListDatabases触发实际数据库操作来验证追踪是否产生。日志方面组件要求以下 MongoDB 驱动日志类别可达见 ConformanceTests.cs 与 ConfigurationSchema.json 中的logLevel定义MongoDB根类别MongoDB.CommandMongoDB.ConnectionMongoDB.InternalMongoDB.SDAM服务器发现与监控MongoDB.ServerSelection服务器选择这些类别可在Logging:LogLevel配置节中按需调整日志级别。注意该组件当前未实现 MetricsConformance 测试中SetMetrics直接抛出NotImplementedExceptionConformanceTests.cs可观测性能力聚焦在追踪与日志两条线上。运行时行为细节值得注意的源码事实连接字符串缺失会抛异常ValidateSettings会调用ConnectionStringValidation.ValidateConnectionStringAspireMongoDBDriverExtensions.cs在创建客户端时若缺少连接字符串将抛出InvalidOperationException提示信息会带出连接名称与配置节路径便于定位问题。IMongoDatabase是连接字符串有库名才注册连接字符串中的库名会被MongoUrl.Create解析只有解析出非空数据库名时才注册IMongoDatabase单例AspireMongoDBDriverExtensions.cs。测试中mongodb://localhost:27017/mydatabase能解析出IMongoDatabase而mongodb://localhost:27017则不能。组件只做客户端集成不负责启动数据库本地开发时数据库实例由 AppHost 中的AddMongoDB通过容器编排拉起Aspire.MongoDB.Driver本身不包含任何容器或服务器逻辑两者的职责边界清晰。更多资源组件与托管集成的官方文档分别为 src/Components/Aspire.MongoDB.Driver/README.md 与 src/Aspire.Hosting.MongoDB/README.md组件公共 API 一览见 api/Aspire.MongoDB.Driver.cs配置 Schema 见 ConfigurationSchema.json完整测试套件位于 tests/Aspire.MongoDB.Driver.Tests/含扩展方法测试、Conformance 测试与基于 Testcontainers 的MongoDbContainerFixture可据此了解组件的全部契约行为。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考