Aspire.Npgsql 使用指南为 .NET 应用接入 PostgreSQL 的官方 Aspire 集成组件【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本指南围绕 Aspire 仓库中 Aspire.Npgsql 组件文档 展开系统讲解如何在 .NET 应用中通过AddNpgsqlDataSource将 PostgreSQL 数据库接入依赖注入DI容器并自动获得健康检查、OpenTelemetry 追踪与指标等可观测性能力。读完本文你将掌握该组件的安装方式、三种配置途径连接字符串、配置提供程序、内联委托、与Aspire.Hosting.PostgreSQLAppHost 扩展的配合用法以及源码层面的实现细节。组件概览Aspire.Npgsql 是 Aspire 面向 PostgreSQL 官方 .NET 客户端 Npgsql 的集成组件。它的核心职责可以概括为一句话在 DI 容器中注册 NpgsqlDataSource用于连接 PostgreSQL 数据库并自动启用对应的健康检查、指标、日志与遥测telemetry。从 Aspire.Npgsql.csproj 可以看到该组件底层依赖的核心包包括Npgsql.DependencyInjection提供AddNpgsqlDataSource扩展负责把NpgsqlDataSource注册进 DI 容器Npgsql.OpenTelemetry提供 Npgsql 的 OpenTelemetry 追踪与指标埋点AspNetCore.HealthChecks.NpgSql提供基于 Npgsql 的数据库健康检查Microsoft.Extensions.Configuration.Binder用于将配置节绑定到NpgsqlSettingsMicrosoft.Extensions.Diagnostics.HealthChecks与OpenTelemetry.Extensions.Hosting承载健康检查与遥测注册。组件对外暴露的公共 API 非常精简核心入口为AspirePostgreSqlNpgsqlExtensions上的两个扩展方法详见 api/Aspire.Npgsql.csAddNpgsqlDataSource(connectionName, ...)注册**默认非键控**的NpgsqlDataSource服务AddKeyedNpgsqlDataSource(name, ...)注册**键控keyed**的NpgsqlDataSource服务适用于一个应用中同时连接多个 PostgreSQL 数据库的场景。快速开始前置条件使用该组件前你需要具备一个可访问的 PostgreSQL 数据库用于连接该数据库的连接字符串Connection String。安装 NuGet 包通过 .NET CLI 安装 Aspire.Npgsql 组件dotnet add package Aspire.Npgsql在 AppHost 中注册数据源在项目的Program.cs即 README 中所说的AppHost.cs中调用AddNpgsqlDataSource扩展方法传入一个连接名称connection name即可把NpgsqlDataSource注册到 DI 容器builder.AddNpgsqlDataSource(postgresdb);这里的postgresdb既用作从ConnectionStrings配置节检索连接字符串的键也用作默认服务的注册名。通过 DI 消费数据源注册完成后即可在任意由 DI 构造的服务中注入NpgsqlDataSource。例如在一个 Web API 控制器中private readonly NpgsqlDataSource _dataSource; public ProductsController(NpgsqlDataSource dataSource) { _dataSource dataSource; }之后就可以用_dataSource创建连接、执行 SQL。NpgsqlDataSource本身是一个轻量的、内部带连接池管理的抽象推荐将它作为长生命周期对象注入使用。配置方式详解组件提供了多种配置数据库连接的途径可依据项目约定灵活选择。所有配置最终都会汇入 NpgsqlSettings 这一设置模型其包含四个可配置项属性类型默认值说明ConnectionStringstring?null要连接的 PostgreSQL 数据库连接字符串DisableHealthChecksboolfalse是否禁用数据库健康检查DisableTracingboolfalse是否禁用 OpenTelemetry 追踪DisableMetricsboolfalse是否禁用 OpenTelemetry 指标上述默认值可以从 ConfigurationSchema.json 中的default字段得到印证。方式一使用连接字符串当连接字符串存放在配置的ConnectionStrings节时只需把该节中的键名传给AddNpgsqlDataSourcebuilder.AddNpgsqlDataSource(myConnection);对应appsettings.json{ ConnectionStrings: { myConnection: Hostmyserver;Databasetest } }连接字符串的具体格式如Host、Port、Username、Password、Database、Pooling等参数遵循 Npgsql 官方连接字符串规范。方式二使用配置提供程序Aspire:Npgsql配置节组件支持 Microsoft.Extensions.Configuration通过Aspire:Npgsql键加载NpgsqlSettings。例如在appsettings.json中配置部分选项{ Aspire: { Npgsql: { DisableHealthChecks: true, DisableTracing: true } } }从源码 AspirePostgreSqlNpgsqlExtensions.cs 可以看到实际的加载逻辑组件先读取Aspire:Npgsql配置节并Bind到settings若使用键控 API还会继续读取Aspire:Npgsql:{name}子节并再次绑定实现公共配置 命名实例专属配置的覆盖机制。配置加载的优先级从低到高为Aspire:Npgsql配置节绑定Aspire:Npgsql:{connectionName}命名子节绑定ConnectionStrings:{connectionName}节中的连接字符串configureSettings内联委托优先级最高最后执行。这一点可由测试 ConnectionNameWinsOverConfigSection 佐证当Aspire:Npgsql:ConnectionString与ConnectionStrings:{name}同时存在时后者生效。方式三使用内联委托inline delegates也可以直接通过ActionNpgsqlSettings configureSettings委托在代码内联设置部分或全部选项例如在代码中禁用健康检查builder.AddNpgsqlDataSource(postgresdb, settings settings.DisableHealthChecks true);内联委托在所有配置读取完成后才被调用见 AspirePostgreSqlNpgsqlExtensions.cs因此它可以覆盖来自配置文件的值。测试 ConnectionStringCanBeSetInCode 验证了代码显式设置的连接字符串会覆盖配置值这一行为。补充自定义 NpgsqlDataSourceBuilder除了配置NpgsqlSettings两个扩展方法还都接受可选的ActionNpgsqlDataSourceBuilder configureDataSourceBuilder委托用于对NpgsqlDataSourceBuilder做进一步定制例如启用类型映射、配置插件等。它会在数据源真正被请求时才执行连接字符串的校验也被延迟到该时刻从而保证异常发生在日志系统就绪之后参见 RegisterNpgsqlServices。多数据库场景键控Keyed注册当一个应用需要同时连接多个 PostgreSQL 数据库时可以使用AddKeyedNpgsqlDataSourcebuilder.AddKeyedNpgsqlDataSource(orders); builder.AddKeyedNpgsqlDataSource(inventory);消费端通过[FromKeyedServices]或GetRequiredKeyedServiceNpgsqlDataSource(name)按名称获取对应实例。测试 CanAddMultipleKeyedServices 验证了默认服务与多个键控服务可以共存且彼此是互不相同的NpgsqlDataSource实例。键控注册同样支持Aspire:Npgsql:{name}专属配置节和内联委托两种定制手段。自动化的可观测性与健康检查调用AddNpgsqlDataSource后组件会根据NpgsqlSettings自动完成三件事详见 AspirePostgreSqlNpgsqlExtensions.cs健康检查注册名为PostgreSql键控时为PostgreSql_{connectionName}的健康检查内部通过NpgSqlHealthCheck与NpgSqlHealthCheckOptions对NpgsqlDataSource发起探测默认开启可通过DisableHealthChecks true关闭追踪Tracing通过AddOpenTelemetry().WithTracing(tp tp.AddNpgsql())接入 Npgsql 的 OpenTelemetry 追踪默认开启可通过DisableTracing true关闭指标Metrics通过WithMetrics(NpgsqlCommon.AddNpgsqlMetrics)接入 Npgsql 指标。在 NpgsqlCommon.cs 中指标注册围绕Npgsqlmeter 展开对于 Npgsql 10.0 之前的旧版本还额外为db.client.commands.duration、db.client.connections.create_time等直方图配置了 OpenTelemetry 规范对齐的桶边界。默认开启可通过DisableMetrics true关闭。此外组件还顺带支持 Npgsql 的日志分类如Npgsql、Npgsql.Command、Npgsql.Connection、Npgsql.Exception、Npgsql.Transaction等的日志级别配置这些分类同样出现在 ConfigurationSchema.json 的logLevel定义中可通过标准Logging:LogLevel配置节按需调整。与 Aspire.Hosting.PostgreSQL 的端到端配合组件的完整工作流往往与 AppHost 侧的Aspire.Hosting.PostgreSQL配合使用。安装 AppHost 扩展包在 AppHost 项目中安装dotnet add package Aspire.Hosting.PostgreSQL在 AppHost 中注册数据库资源在AppHost项目的Program.cs中注册 Postgres 服务器与数据库并通过WithReference建立项目依赖var postgresdb builder.AddPostgres(pg).AddDatabase(postgresdb); var myService builder.AddProjectProjects.MyService() .WithReference(postgresdb);从 PostgresBuilderExtensions.cs 的源码可以看到AddPostgres在本地开发模式下会启动一个 PostgreSQL 容器内部端口固定为 5432默认使用scram-sha-256认证并为服务器资源注册内置健康检查AddDatabase见 PostgresBuilderExtensions.cs则会在服务器就绪后自动执行CREATE DATABASE完成建库并注册数据库级健康检查。容器内数据目录因 PostgreSQL 版本而异17 及更早为/var/lib/postgresql/data18 及之后为/var/lib/postgresqlWithDataVolume/WithDataBindMount会自动根据镜像 tag 选择正确路径。在业务服务中消费连接WithReference会在MyService中注入名为postgresdb的连接connection name。因此在MyService项目的Program.cs中即可直接消费builder.AddNpgsqlDataSource(postgresdb);这正是AppHost 编排 组件消费的标准闭环AppHost 负责创建与配置数据库资源Aspire.Npgsql组件负责在业务项目中以NpgsqlDataSource的形式提供连接并自动附带健康检查与可观测性。AppHost 侧的其他实用扩展除基础用法外Aspire.Hosting.PostgreSQL还提供了若干开箱即用的管理工具扩展.WithPgAdmin()附加 pgAdmin 4 Web 管理界面见 PostgresBuilderExtensions.cs.WithPgWeb()附加轻量级的 pgweb 浏览器端管理界面见 PostgresBuilderExtensions.cs.WithPostgresMcp()为数据库附加一个基于 SSE 传输的 Postgres MCP 服务器容器见 PostgresBuilderExtensions.cs当前标记为实验性功能ASPIREPOSTGRES001.WithDataVolume()/.WithDataBindMount()持久化数据库数据.WithPassword()/.WithUserName()显式配置数据库凭据.WithHostPort()固定宿主端口。日志与诊断配置汇总结合组件与配置架构一张完整的appsettings.json示例可涵盖连接字符串、功能开关与日志级别{ ConnectionStrings: { postgresdb: Hostmyserver;Databasetest }, Aspire: { Npgsql: { ConnectionString: Hostmyserver;Databasetest, DisableHealthChecks: false, DisableTracing: false, DisableMetrics: false } }, Logging: { LogLevel: { Default: Information, Npgsql: Information, Npgsql.Command: Warning, Npgsql.Connection: Warning, Npgsql.Exception: Error, Npgsql.Copy: Warning, Npgsql.Replication: Warning, Npgsql.Transaction: Warning } } }注意ConnectionStrings与Aspire:Npgsql:ConnectionString均可提供连接字符串但按源码加载顺序前者优先configureSettings内联委托的优先级最高可覆盖一切配置文件来源。测试与验证仓库为组件提供了完整的单元测试覆盖主要位于 tests/Aspire.Npgsql.Tests/AspirePostgreSqlNpgsqlExtensionsTests.cs关键验证点包括从 ConnectionStrings 正确读取连接字符串ReadsFromConnectionStringsCorrectly同时覆盖普通与键控两种注册方式代码中设置连接字符串可覆盖配置ConnectionStringCanBeSetInCodeConnectionStrings 优先于 Aspire:Npgsql 配置节ConnectionNameWinsOverConfigSection自定义NpgsqlDataSourceBuilder委托会被执行CustomDataSourceBuilderIsExecuted多键控服务互不干扰CanAddMultipleKeyedServices。另有 ConformanceTests.cs 与 NpgsqlPublicApiTests.cs 分别用于保证组件遵循 Aspire 组件统一约定以及公共 API 面稳定。若你希望进一步研究组件的实现推荐按以下顺序阅读AspirePostgreSqlNpgsqlExtensions.cs —— 注册与配置加载的核心实现NpgsqlSettings.cs —— 设置模型ConfigurationSchema.json —— 配置架构与默认值声明PostgresBuilderExtensions.cs —— AppHost 侧的资源编排扩展。总结Aspire.Npgsql 组件以极低的接入成本一行AddNpgsqlDataSource将 PostgreSQL 连接、健康检查与可观测性能力整合进 Aspire 应用并提供了连接字符串、配置节、内联委托三层递进式配置手段配合Aspire.Hosting.PostgreSQL的AddPostgres/AddDatabase/WithReference即可完成从本地容器数据库到业务服务消费连接的完整端到端闭环。无论是单体应用还是需要同时连接多个数据库的复杂场景该组件都能通过普通注册与键控注册两种方式灵活应对。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考