Aspire 集成 Azure Cosmos DB 实战指南深入解析 Aspire.Microsoft.Azure.Cosmos 组件【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本文以 .NET Aspire 仓库中的Aspire.Microsoft.Azure.Cosmos组件为核心系统讲解如何通过依赖注入DI注册CosmosClient、以多种方式配置连接连接字符串 / AccountEndpoint / 配置提供程序 / 内联委托、启用健康检查与 OpenTelemetry 可观测性以及在 AppHost 中使用Aspire.Hosting.Azure.CosmosDB编排 Azure Cosmos DB 资源含本地模拟器。读完本文你将掌握在 Aspire 应用中开箱即用地连接 Azure Cosmos DB 的完整方案并理解其底层实现原理。组件定位与设计目标Aspire.Microsoft.Azure.Cosmos是 Aspire 官方组件库位于 src/Components中面向 Azure Cosmos DB 的集成组件。它解决了手工实例化CosmosClient时的三类常见痛点注册与生命周期管理将 CosmosClient 注册为 DI 容器中的单例Singleton并保证其在整个应用生命周期内只创建一次配置约定化统一从ConnectionStrings配置节或Aspire:Microsoft:Azure:Cosmos配置节读取连接信息遵循 Aspire 的命名约定可观测性开箱即用自动关联健康检查、日志Logging与分布式追踪Telemetry/Tracing无需额外接线。组件的核心入口是AspireMicrosoftAzureCosmosExtensions静态类AspireMicrosoftAzureCosmosExtensions.cs它向开发者暴露了一系列Add*扩展方法全部作用于IHostApplicationBuilder。从方法签名可以看到整个组件只依赖标准接口public static void AddAzureCosmosClient( this IHostApplicationBuilder builder, string connectionName, ActionMicrosoftAzureCosmosSettings? configureSettings null, ActionCosmosClientOptions? configureClientOptions null)内部流程非常清晰先GetSettings读取并合并配置再GetClientOptions构建CosmosClientOptions然后注册单例并追加健康检查。下文将逐一展开。快速开始前置条件与安装前置条件一个Azure 订阅可免费创建一个Azure Cosmos DB 账户NoSQL API使用 .NET 8 与 Aspire 工作负载的宿主项目。安装 NuGet 包在需要使用 Cosmos DB 的服务项目即调用AddAzureCosmosClient的项目中执行dotnet add package Aspire.Microsoft.Azure.Cosmos注意该包属于 Aspire 组件Components与用于编排资源的 Hosting 包Aspire.Hosting.Azure.CosmosDB职责不同后者在“AppHost 扩展”一节单独讲解。两者的分工是Hosting 包在 AppHost 中定义资源与连接关系组件包在具体服务中消费连接。注册与使用把 CosmosClient 交给 DI在承载服务的应用项目中Aspire 当前模板为Program.cs早期文档习惯称之为AppHost.cs调用AddAzureCosmosClient即可注册CosmosClientbuilder.AddAzureCosmosClient(cosmosConnectionName);connectionName是连接名称它同时用于在ConnectionStrings配置节中查找连接字符串。注册完成后CosmosClient会以单例形式存在于 DI 容器中任何构造函数注入即可获取例如在一个 Web API 控制器中private readonly CosmosClient _client; public ProductsController(CosmosClient client) { _client client; }更细粒度的注册Container 与 Database除CosmosClient外组件还提供了直接注册Container和Database的方法同样在 AspireMicrosoftAzureCosmosExtensions.cs 中定义AddAzureCosmosContainer(connectionName)注册Container单例底层调用client.GetContainer(settings.DatabaseName, settings.ContainerName)。要求连接字符串中必须包含Database和Container名称否则抛出InvalidOperationException见源码中AddAzureCosmosContainer的校验逻辑AddAzureCosmosDatabase(connectionName)注册Database单例返回CosmosDatabaseBuilder以支持链式注册同一个数据库下的多个容器。数据库名称缺失时同样会抛异常CosmosDatabaseBuilder.cs 中AddDatabase的校验逻辑。CosmosDatabaseBuilder支持对同一数据库注册多个键控keyed容器builder.AddAzureCosmosDatabase(cosmos) .AddKeyedContainer(orders) .AddKeyedContainer(products);AddKeyedContainer优先使用连接字符串中的Container名称若未提供则回退到name参数见 CosmosDatabaseBuilder.cs 中AddKeyedContainer的实现。键控注册多个实例共存当应用中需要连接多个Cosmos DB 账户或数据库时可以使用键控注册builder.AddKeyedAzureCosmosClient(inventory); builder.AddKeyedAzureCosmosClient(analytics);它们分别以inventory、analytics为ServiceDescriptor.ServiceKey注册消费时通过[FromKeyedServices(inventory)]或GetRequiredKeyedServiceCosmosClient(inventory)获取。同理也有AddKeyedAzureCosmosContainer与AddKeyedAzureCosmosDatabase。连接配置详解四种配置方式的完整继承组件的配置目标是要么提供AccountEndpoint要么提供ConnectionString二者必居其一否则在解析客户端时会抛出InvalidOperationException异常信息在 AspireMicrosoftAzureCosmosExtensions.cs 的GetCosmosClient方法末尾。以下四种配置方式可以组合使用优先级从低到高依次为配置提供程序 → 连接字符串 → 内联委托。方式一使用连接字符串ConnectionStrings 节在appsettings.json的ConnectionStrings节中按连接名称提供连接信息代码中只需builder.AddAzureCosmosClient(cosmosConnectionName)即可自动拾取。支持两种格式。1Account Endpoint推荐仅提供账户端点 URI配合MicrosoftAzureCosmosSettings.Credential属性完成认证。若未显式配置Credential组件会依据当前环境自动创建默认的TokenCredential即 DefaultAzureCredential 语义兼容本地开发、Azure CLI、托管标识等场景{ ConnectionStrings: { cosmosConnectionName: https://{account_name}.documents.azure.com:443/ } }2完整连接字符串使用包含账户密钥的完整 Azure Cosmos DB 连接字符串{ ConnectionStrings: { cosmosConnectionName: AccountEndpointhttps://{account_name}.documents.azure.com:443/;AccountKey{account_key}; } }测试代码AspireMicrosoftAzureCosmosExtensionsTests.cs证实连接字符串还支持附加Databasedb;Containermycontainer之类的子段例如AccountEndpointhttps://localhost:8081;AccountKeyfake;Databasetestdb;Containermycontainers;解析逻辑GetSettings中会把这些子段提取并写入settings.DatabaseName与settings.ContainerName供AddAzureCosmosContainer/AddAzureCosmosDatabase使用DisableServerCertificateValidationTrue等开关也可内联在连接字符串中。方式二使用配置提供程序Aspire:Microsoft:Azure:Cosmos 节组件支持Microsoft.Extensions.Configuration的任意配置源JSON、环境变量、用户机密等统一从Aspire:Microsoft:Azure:Cosmos键加载MicrosoftAzureCosmosSettings。以下appsettings.json示例关闭了追踪{ Aspire: { Microsoft: { Azure: { Cosmos: { DisableTracing: false } } } } }所有可配置项在 ConfigurationSchema.json 中有完整定义与 MicrosoftAzureCosmosSettings.cs 的属性一一对应配置属性类型默认值说明ConnectionStringstringnull要连接的 Cosmos DB 连接字符串含密钥AccountEndpointstring (uri)null账户端点 URI如https://{account_name}.documents.azure.com不得包含共享访问签名SAS需配合Credential使用CredentialTokenCredentialnull用于认证端点的凭据缺省时自动创建默认凭据DatabaseNamestringnull要连接的数据库名称ContainerNamestringnull要连接的容器名称DisableHealthChecksbooleanfalse是否禁用健康检查DisableTracingbooleanfalse是否禁用 OpenTelemetry 追踪此外源码中的GetSettings还会尝试绑定Aspire:Microsoft:Azure:Cosmos:{connectionName}这一命名子节因此不同连接可拥有各自独立的设置覆盖这是容易被忽略但非常实用的特性。方式三使用内联委托configureSettingsAddAzureCosmosClient的可选参数ActionMicrosoftAzureCosmosSettings configureSettings允许在代码中设置部分或全部设置项它在配置绑定之后执行因此优先级最高。例如在代码中禁用追踪builder.AddAzureCosmosClient(cosmosConnectionName, settings settings.DisableTracing true);方式四配置 CosmosClientOptionsconfigureClientOptions第二个可选参数ActionCosmosClientOptions configureClientOptions用于定制底层 SDK 的CosmosClientOptions。例如为所有请求的User-Agent附加ApplicationName后缀builder.AddAzureCosmosClient(cosmosConnectionName, configureClientOptions: clientOptions clientOptions.ApplicationName myapp);从 AspireMicrosoftAzureCosmosExtensions.cs 的GetClientOptions可以看到几处关键的框架级强制设置分布式追踪默认开启clientOptions.CosmosClientTelemetryOptions.DisableDistributedTracing false这是日志与追踪生效的前提ApplicationName 拼接组件会把内置的CosmosApplicationName与你传入的ApplicationName拼接成{CosmosApplicationName}/{ApplicationName}格式保证请求可归因模拟器自动适配检测到模拟器连接字符串时自动设置ConnectionMode.Gateway与LimitToEndpoint true详见下文模拟器一节。健康检查让下游依赖感知 Cosmos 状态默认情况下组件会注册一个健康检查其名称为Microsoft.Azure.Cosmos源码中的HealthCheckName常量。该检查通过调用CosmosClient.ReadAccountAsync()读取账户属性来验证账户可达性——实现见 AzureCosmosDbHealthCheck.cs其注释说明该实现参照了 AspNetCore.Diagnostics.HealthChecks 的账户级探测模式并对不支持CancellationToken的ReadAccountAsync通过WaitAsync做了取消支持。健康检查会自动挂载到应用的/health端点。这意味着依赖方通过WaitFor等待服务 HTTP 健康或 Kubernetes 就绪探针时在 Cosmos DB 不可达期间不会误报健康。键控注册时健康检查名称会带上服务键后缀Microsoft.Azure.Cosmos_{serviceKey}避免多个实例相互覆盖。关闭健康检查通过配置{ Aspire: { Microsoft: { Azure: { Cosmos: { DisableHealthChecks: true } } } } }或通过内联委托builder.AddAzureCosmosClient(cosmosConnectionName, settings settings.DisableHealthChecks true);可观测性日志与遥测日志Logging组件启用了 Cosmos DB 请求诊断日志。根据 ConfigurationSchema.json 中logLevel定义可通过标准Logging:LogLevel配置控制名为Azure-Cosmos-Operation-Request-Diagnostics的日志类别{ Logging: { LogLevel: { Azure-Cosmos-Operation-Request-Diagnostics: Information } } }遥测Tracing当DisableTracing为false默认时GetClientOptions会执行builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder { tracerProviderBuilder.AddSource(Azure.Cosmos.Operation); });即向 OpenTelemetry 的 TracerProvider 注册Azure.Cosmos.Operation这个 ActivitySource将每个 Cosmos DB 操作的分布式追踪数据延迟、状态、请求诊断等接入 Aspire Dashboard 或其他 OpenTelemetry Collector。这使你在 Aspire 的仪表盘中可以直接按资源、按操作追踪到具体的 Cosmos 请求链路。AppHost 扩展用 Aspire.Hosting.Azure.CosmosDB 编排资源前面所有内容都是消费端的工作资源侧的编排由 Hosting 包完成。在AppHost 项目中安装dotnet add package Aspire.Hosting.Azure.CosmosDB然后在 AppHost 的Program.cs中定义 Cosmos DB 资源并通过WithReference将连接信息注入服务项目var cosmosdb builder.ExecutionContext.IsPublishMode ? builder.AddAzureCosmosDB(cdb).AddCosmosDatabase(cosmosdb) : builder.AddConnectionString(cosmosdb); var myService builder.AddProjectProjects.MyService() .WithReference(cosmosdb);这里需要理解三个方法的分工AddAzureCosmosDB(cdb)向应用模型添加一个 Azure Cosmos DB 资源发布模式下会联动 Azure 预配逻辑源码中AddAzureCosmosDB首先调用AddAzureProvisioning()见 AzureCosmosDBExtensions.csAddCosmosDatabase(cosmosdb)进一步声明其中的数据库AddConnectionString(cosmosdb)从 AppHost 配置例如用户机密的ConnectionStrings:cosmosdb键读取现成的连接信息适合本地开发不触发 Azure 预配的场景WithReference(cosmosdb)把连接信息传递到MyService项目在该项目中表现为名为cosmosdb的连接字符串。在MyService项目的Program.cs中消费builder.AddAzureCosmosClient(cosmosdb);如此便完成了AppHost 定义资源 → 注入连接 → 服务端注册客户端的完整闭环。ExecutionContext.IsPublishMode分支保证了同一套代码在dotnet run本地与dotnet publish/azd deploy发布时分别走连接字符串与 Azure 资源两条路径。使用本地模拟器EmulatorAspire 支持通过本地容器运行 Azure Cosmos DB 模拟器便于离线开发与测试。在 AppHost 中// AppHost var cosmosdb builder.AddAzureCosmosDB(cosmos).RunAsEmulator();AppHost 启动时会自动拉起一个运行 Azure Cosmos DB 的本地容器默认使用 Linux 版 vNext 模拟器镜像。服务端代码无需任何改动// Service code builder.AddAzureCosmosClient(cosmos);从 AzureCosmosDBExtensions.cs 的实现看RunAsEmulator在IsPublishMode下会直接返回原资源即发布时不启动模拟器同时组件侧的GetClientOptions会检测模拟器连接字符串并自动切换ConnectionMode.Gateway与LimitToEndpoint true以匹配模拟器的网络模型。源码中还有RunAsClassicEmulator经典版模拟器与已标记[Obsolete]的RunAsPreviewEmulator请改用RunAsEmulator以及仅对 vNext 模拟器可用的WithDataExplorer用于暴露 Data Explorer 端点需配合ENABLE_EXPLORER环境变量。源码与测试佐证行为是如何被保证的组件的行为并非文档承诺而是有明确实现与测试约束的连接字符串解析AspireMicrosoftAzureCosmosExtensionsTests.cs 中的AddAzureCosmosClient_EnsuresConnectionStringIsCorrect用 7 组InlineData覆盖了含/不含AccountKey、Database、Container、DisableServerCertificateValidation及纯端点 URI 等组合逐一断言最终client.Endpoint的规范化结果AddAzureCosmosClient_FailsWithError则验证了非法连接字符串会抛出包含AccountEndpoint缺失信息的异常Database / Container 注册隔离AddAzureCosmosDatabase_RegistersDatabaseService断言注册数据库后容器中不存在裸CosmosClient单例Assert.Null(client)说明 Database/Container 注册并不向 DI 暴露多余的客户端实例避免资源泄漏与误用键控注册AddKeyedAzureCosmosDatabase_RegistersDatabaseService等测试验证了键控路径下服务键与实例的正确绑定配置节绑定GetSettings中configSection.Bind(settings)与namedConfigSection.Bind(settings)的两次绑定以及CosmosUtils.ParseConnectionString对连接字符串的解析共同支撑了前文多种配置方式可叠加、连接字符串子段可提取的结论健康检查AddCosmosHealthCheck在DisableHealthChecks为true时直接短路返回避免无谓的注册开销。这些测试位于 tests/Aspire.Microsoft.Azure.Cosmos.Tests 目录是理解组件契约边界的最佳入口。组件全景速查关注点API / 配置位置注册客户端AddAzureCosmosClient/AddKeyedAzureCosmosClientAspireMicrosoftAzureCosmosExtensions.cs注册容器AddAzureCosmosContainer/AddKeyedAzureCosmosContainer同上注册数据库多容器AddAzureCosmosDatabaseAddKeyedContainerCosmosDatabaseBuilder.cs设置项Aspire:Microsoft:Azure:Cosmos及命名子节MicrosoftAzureCosmosSettings.cs、ConfigurationSchema.json健康检查默认启用DisableHealthChecks关闭AzureCosmosDbHealthCheck.cs编排资源AddAzureCosmosDB/RunAsEmulator/WithReferenceAzureCosmosDBExtensions.cs行为契约测试连接解析 / 注册隔离 / 键控注册AspireMicrosoftAzureCosmosExtensionsTests.cs小结Aspire.Microsoft.Azure.Cosmos组件用极简的 API 封装了 Azure Cosmos DB 接入的全部样板代码单例注册、双轨认证连接字符串 / AAD 凭据、多容器编排、健康检查与 OpenTelemetry 追踪。配合Aspire.Hosting.Azure.CosmosDB的 AppHost 编排能力开发者可以用同一套代码平滑地在本地模拟器、已配置连接字符串和 Azure 托管资源之间切换这正是 Aspirecode-first、可扩展、可观测开发与部署体验的典型体现。建议读者结合上述源码路径与测试用例进一步研读在真实项目中优先采用 AccountEndpoint 默认凭据的推荐配置并保持健康检查默认开启以保障依赖拓扑的正确性。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考