简介对于.NET Framework 4.5环境下需要接入PostgreSQL的开发者这份726KB的压缩包提供了完整的连接API组件。资源共19个文件核心是Npgsql.dll及其依赖的Mono.Security.dll前者提供ADO.NET兼容的数据访问接口后者用于SSL连接和证书验证等安全支持同时包含Entity Framework适配器Npgsql.EntityFramework.dll及Legacy版本、3个XML文档和PDB调试符号便于API查阅与错误定位。包内还附有README说明和LICENSE许可协议可帮助了解安装配置与合规使用。已有892人学习适合正在使用.NET 4.5构建PostgreSQL数据交互场景的中高级开发者尤其需要Entity Framework集成或安全连接验证的工程。1. 老 .NET Framework 4.5 项目连 PostgreSQL先分清 Npgsql.dll 和 Mono.Security.dll 各管什么在 .NET Framework 4.5 的老业务系统里接 PostgreSQL绕不开标题里这两个 DLLNpgsql.dll 是社区维护的 ADO.NET 数据提供程序把 System.Data 接口翻译成 PostgreSQL 的 wire protocolMono.Security.dll 则是 Npgsql 2.x 时代自带的 SSL 支撑库新版已经不需要。很多人把两个 DLL 一起拷进 bin编译通过部署到服务器却在 Open() 时抛 FileNotFoundException 或 SSL 握手失败根子都在版本混搭。下面按落地顺序讲先选对 Npgsql 版本再写出最小连接然后逐个排查 SSL、SCRAM、DLL 加载三类高频坑最后给一个验证连接与版本号的检查习惯。适合正在维护遗留系统的开发也适合在 Windows 上做 PostgreSQL 适配的运维。2. 版本选型.NET Framework 4.5 能吃下哪一版 Npgsql2.1 Npgsql 2.x / 3.x / 4.x三条版本线的兼容边界Npgsql 在 NuGet 上从 2.x 一路走到 7.x但目标框架划分得很清楚。2.x 时代是给 .NET Framework 2.0/3.5/4.0 用的最后一个版本停在 2.0.11 附近最明显的特征是压缩包里同时给你 Npgsql.dll 和 Mono.Security.dllSSL 功能由后者提供。3.x 是专门为 .NET Framework 4.5 重写的一代从 3.0 开始去掉 Mono.Security 依赖改用 System.Net.Security 走 TLS这一代最后的小版本是 3.2.7。4.x 是又一次大重写目标框架直接抬到 .NET Framework 4.5.2 和 .NET Standard 2.05.x/6.x 基本只服务 .NET Core / .NET 5到了 7.x 就不再碰 .NET Framework。这里最容易踩的坑是网上教程很多让直接 Install-Package Npgsql结果把最新版装进了 .NET Framework 4.5 项目。编译可能过包里的 netstandard 资产会被兼容过来一运行就报程序集加载失败或要求更高运行时。判断标准很简单csproj 里 TargetFrameworkVersion 是 v4.5就用 3.2.7如果项目能接受升到 v4.5.2 或更高才轮得到 4.x。Npgsql 版本线目标框架Mono.Security.dll与 PostgreSQL 兼容情况2.0.x ~ 2.2.x.NET 2.0 / 3.5 / 4.0需要PG 9.x ~ 10.x 可跑连 PG 14 默认 SCRAM 会认证失败3.0.x ~ 3.2.x.NET Framework 4.5不需要PG 9.x ~ 15.x 均可3.2.7 对 SCRAM 支持成熟4.0.x.NET Framework 4.5.2 / .NET Standard 2.0不需要全面重写参数、类型映射行为差异大5.x ~ 7.x.NET Core / .NET 5不需要不再支持 .NET Framework提示项目是 v4.5 还是 v4.5.2以 csproj 里TargetFrameworkVersionv4.5/TargetFrameworkVersion这一行为准别在 VS 属性页里凭印象判断。很多遗留系统动不了框架版本一抬就牵出第三方控件兼容问题所以 .NET Framework 4.5 这条线的终点就是 3.2.7。如果你的团队能接受把目标框架抬到 4.5.2用 4.x 在异步支持和类型映射上会更省心但那属于改框架级别的工作量不是加一个 DLL 能解决的。2.2 Mono.Security.dll 从哪来为什么新分发里看不到它Mono.Security.dll 的来历要回到 Npgsql 2.x 的年代。那时 .NET Framework 2.0/3.5 在 SSL 客户端证书、TLS 握手这些场景上支持不完整尤其是跨平台跑在 Mono 托管环境里的时候Npgsql 直接复用了 Mono 项目编译出来的 Security 程序集来完成 SSL 传输层。所以它既不是 PostgreSQL 官方文件也不是 Npgsql 3.x 之后的组成部分。判断手里资源属于哪个年代有个土办法凡是让同时引用 Npgsql.dll 和 Mono.Security.dll的教程或安装包基本是 2013 年前后的 Npgsql 2.x 分发到了 3.x包里只有一个 Npgsql.dll外加 Npgsql.xml 注释文档。如果你在一个 3.x 项目里硬把 Mono.Security.dll 留着两个程序集之间并没有依赖关系多数情况是白占空间反过来2.x 项目少了 Mono.Security.dll开 SSL 连接时必炸。这个 DLL 该不该留完全取决于 Npgsql 的大版本不能靠多个文件多份保险的思维来定。2.3 用 NuGet 锁版本还是手工拷贝 DLL两条落地点第一条路也是我最推荐的路是 NuGet 锁版本安装Install-Package Npgsql -Version 3.2.7在 VS2013/2015/2017 的 Package Manager Console 里执行强制装到 3.2.7不让 NuGet 自动解析成 4.x 或更高。装完检查 packages.config 或 csproj 里的引用版本号是不是 3.2.7.0同时确认没有把 2.x 的老引用残留下来。升级老项目时如果 bin 目录里躺着旧的 Npgsql.dll 和 Mono.Security.dll先清空 bin 再重新生成避免新旧程序集混在输出目录里。第二条路是离线环境手工拷贝。从 nuget.org 下载 Npgsql 3.2.7 的 .nupkg把扩展名改成 .zip 解压里面会有 lib/net45/Npgsql.dll 和 lib/net45/zh-Hans 等资源目录。取 net45 目录下的 DLL 拷到项目 bin 即可。注意别拿 lib/netstandard2.0 目录下的文件放进 .NET Framework 4.5 项目某些场景能编译但运行时行为不可控。装完如果还报程序集加载失败检查 app.config 或 web.config 里的 assemblyBinding 节点。有些老项目升级过一次 NuGet配置文件里残留着旧版本的 bindingRedirect重定向目标是 3.0.0.0实际 DLL 是 3.2.7.0运行时就找不到程序集。把 redirect 删除或改成 3.2.7.0 再试。另外确认 packages 目录跟着仓库走别让 csproj 的 HintPath 指向本机私有缓存路径。还有一句部署提醒如果是内网离线 Windows 环境装 Npgsql 之前先把 PostgreSQL 服务端装好、数据目录初始化完成。Windows 上postgresql数据库启动服务失败在等待服务器启动时超时这类报错通常是服务端没起来和客户端 DLL 没有关系别在客户端排查上耗时间。3. 最小连接落地连接字符串、池参数与第一个查询3.1 连接字符串必填项与推荐默认值Npgsql 的连接字符串和 SqlClient 不是一个方言键名不区分大小写但建议统一写法。必填项是 Server、Port、Database、User Id、Password别把 Password 明文写在 app.config 里至少在部署前用配置加密或环境变量顶替。下面是我在 .NET Framework 4.5 项目里常用的底线配置Server127.0.0.1;Port5432;Databaseappdb;User Idapp_user;Passwordyour_password;Poolingtrue;Min Pool Size1;Max Pool Size20;Timeout15;Command Timeout30;SSL ModePrefer;逐个说明Server 写 IP 而不是 localhost避免部分环境下 DNS 解析拖慢建连Port 默认 5432换了端口必须显式写Pooling 在 Npgsql 3.x 默认就是 true写上是为了让接手的人一眼看到Timeout 是建连超时秒15 够用Command Timeout 是单条 SQL 的执行超时默认偏短我一般调到 30真正慢的 SQL 单独在命令对象上加大。SSL Mode 在 3.x 里取值 Disable / Prefer / Require内网且链路可信时用 Prefer公网必须 Require。字符集方面连接串不用刻意设 EncodingNpgsql 默认走 UTF-8。中文乱码多数是 PostgreSQL 数据库本身的编码不是 UTF8属于建库问题不是连接问题。提示连接字符串的键名在 Npgsql 3.x 中按 PascalCase 或空格分隔两种写法都认例如 CommandTimeout 与 Command Timeout 等价但别在同一串里混合风格排错时纯属浪费精力。3.2 打开连接并执行第一个查询最小 C# 代码直接贴一个能编译的最小控制台程序。关键在于用 NpgsqlConnectionStringBuilder 构造连接串而不是手拼字符串手拼最容易在密码含特殊字符时翻车。using System; using Npgsql; class Program { static void Main(string[] args) { var builder new NpgsqlConnectionStringBuilder { Host 127.0.0.1, // 等价于 Server两种写法都行 Port 5432, Database appdb, UserName app_user, Password your_password, Pooling true, MaxPoolSize 20, Timeout 15, CommandTimeout 30 }; using (var conn new NpgsqlConnection(builder.ConnectionString)) { conn.Open(); using (var cmd new NpgsqlCommand(SELECT version();, conn)) { Console.WriteLine(cmd.ExecuteScalar()); } } } }代码逻辑分三段Builder 把参数结构化成标准连接串using 保证连接 Close 后归还连接池命令对象同样用 using 释放。这里有一个 .NET Framework 4.5 上常见的黑匣子行为Open() 抛异常时内层异常往往比外层更有用比如 SSL 证书问题会包在 AuthenticationException 里排查先看 InnerException别盯着最外层一句错误码猜。带参数的查询要避免字符串拼接。Npgsql 3.x 支持 和 : 两种占位符参数用 AddWithValue 或显式 NpgsqlParameter 都可以using (var conn new NpgsqlConnection(builder.ConnectionString)) { conn.Open(); using (var cmd new NpgsqlCommand( SELECT id, name FROM users WHERE created_at since ORDER BY id LIMIT limit;, conn)) { cmd.Parameters.AddWithValue(since, DateTime.UtcNow.AddDays(-7)); cmd.Parameters.AddWithValue(limit, 100); using (var reader cmd.ExecuteReader()) { while (reader.Read()) { Console.WriteLine(${reader.GetInt32(0)}\t{reader.GetString(1)}); } } } }AddWithValue 的隐患是类型推断DateTime 参数会被映射成 timestamp 或 timestamptz取决于列类型如果列是 timestamptz传进来的 DateTime.Kind 是 Utc 还是 Local 会直接影响结果和时区偏移。所以宁可显式 NpgsqlDbType也别在类型推断上赌。3.3 连接池、超时与 Keepalive三个最常调的参数连接池是 Npgsql 默认开启的Max Pool Size 默认值不高业务并发一大就爱报 Timeout expired。Min Pool Size 设 1 的作用是让进程启动后先建一条连接做预热避免第一个请求承担建连开销。Keepalive 参数单位秒在 3.x 里存在默认 0 表示不启用我一般设 15 到 30专门对付防火墙或 NAT 把空闲连接静默回收的问题连接看起来还在对端实际已断开下次请求直接抛异常。服务端对应的是 postgresql.conf 里 tcp_keepalives_idle两边配合才能彻底解决。另一个常被当玄学的坑是 Command Timeout。很多人把连接池耗尽归因到并发实际是一条慢 SQL 把连接占满了。看 pg_stat_activity 里的 state 列如果是 idle in transaction说明事务没提交还占着连接如果是 active 且超过 30 秒优先排查 SQL 和索引而不是网络。连接泄漏的话代码里强制用 using 或 try/finally Dispose泄漏一个少一个池内连接这个问题在长跑服务里比 SSL 更致命。4. 高频踩坑与排查SSL 握手、SCRAM 认证与 DLL 加载失败4.1 现象一Open() 就抛 SSL 或 TLS 异常现象是本地连开发库正常换到配了 SSL 的生产库Open() 直接抛 AuthenticationException内层可能是 The remote certificate is invalid according to the validation procedure也可能是 TLS 握手失败。原因分两类必须分开判断一类是 PostgreSQL 服务器证书是自签名或域名不匹配Npgsql 3.x 默认校验服务端证书链另一类是 .NET Framework 4.5 的 SslStream 默认协商 TLS 1.0而新版 PostgreSQL 在 OpenSSL 1.1.1 的发行版上往往不再接受 TLS 1.0/1.1。解决第一步是定位类别把连接串临时改成 SSL ModeDisable如果问题消失说明是证书或 TLS 协商问题而不是密码或网络问题。内网自签证书场景下Npgsql 3.x 提供事件回调conn.ValidateRemoteCertificateCallback (sender, cert, chain, errors) true;这个回调返回 true 表示无条件信任只能在明确知道证书来源的内网环境用公网这样做等于把传输层安全关掉。TLS 版本问题的解法有两个层次代码里在建连前执行 System.Net.ServicePointManager.SecurityProtocol System.Net.SecurityProtocolType.Tls12或者直接在 Windows 注册表启用 Schannel 的 TLS 1.2 客户端并重启。代码方式多数情况生效注册表方式要重启且影响整机其他程序改动前先备份。4.2 现象二报不支持的认证方式或密码错误连接 PG 14 以上的库时报 authentication method 10 not supported或者密码明明对却说认证失败。原因是 PostgreSQL 14 起默认的密码认证方式是 scram-sha-256而 Npgsql 2.x 和 3.x 早期小版本只实现 md5。升级到 3.2.7 是最省事的解法这一版对 SCRAM 的处理已经稳定。如果项目连 3.2.7 都升不动只能从服务端迁就把 pg_hba.conf 里对应 host 行的 auth-method 从 scram-sha-256 改成 md5保存后执行 pg_reload_conf()。这里有一个容易漏的细节如果该用户当初是用 scram 方式保存的密码光改 pg_hba.conf 没用因为服务端存的是 SCRAM 散列不是 MD5 散列。需要把 postgresql.conf 里的 password_encryption 临时设为 md5重新执行 ALTER USER xxx PASSWORD 新密码;再改回 scram。整个过程记一条变更记录避免几天后别人排查时一头雾水。4.3 现象三部署机报 FileNotFoundException缺 Mono.Security.dll本地开发机编译运行正常发布到服务器后在第一次 Open() 时报 FileNotFoundException内容是找不到 Mono.Security.dll。这种报错在 .NET Framework 项目里太典型开发机 bin 里有发布时被某个排除规则过滤掉了或者教程只让引用 Npgsql.dll 忘了它的依赖。判断依赖关系最直接的办法是用程序集绑定日志工具 fuslogvw.exe把加载失败的 DLL 名称和路径打出来而不是瞎猜。解决要看版本如果是 Npgsql 2.x把 Npgsql.dll 和 Mono.Security.dll 放在同一目录并保持同一压缩包里的版本两个都要引用如果是 3.x应当删除对 Mono.Security.dll 的引用重新从 NuGet 拉干净的 3.2.7然后清空 bin 再发布。最怕的是 bin 里同时躺着 2.x 和 3.x 的 Npgsql.dll 以及一个来历不明的 Mono.Security.dll程序集加载跟抽盲盒一样删干净重来是唯一出路。4.4 现象四连接偶发超时池被耗尽现象是服务跑一阵子后请求陆续报 Timeout expired重启服务又正常过段时间复发。先看 pg_stat_activity如果大量连接处于 idle in transaction基本可以断定是事务没提交就返回了结果连接被长期占用如果连接数顶到池上限且都是 active则是慢 SQL 堆积。前者是代码问题后者是 SQL 或索引问题别一上来就调 Max Pool Size 掩盖。应急手段可以临时调大 Max Pool Size但这只是后悔药治标不治本。正确姿势是检查所有连接是否在 using 或 try/finally 里释放事务分支里有没有遗漏 Commit / Rollback以及是否把网络请求写进了事务内。连接问题特别严重时可以调用 NpgsqlConnection.ClearAllPools() 立刻回收空闲连接但正在使用的连接不受影响别指望它解决泄漏。4.5 现象五服务端没启动误报连接超时最后一条最容易迷惑人。客户端报连接超时或 Timeout expired直觉是网络或连接池问题结果 Windows 事件日志里写着postgresql数据库启动服务失败在等待服务器启动时超时。这是 PostgreSQL 服务进程在启动阶段挂掉了常见原因是数据目录权限不对、postgresql.conf 里参数写错、或磁盘空间占满。排查顺序是固定的先看数据目录下的 postgresql-*.log 日志文件时间戳对得上启动失败时间的就是根因再用 pg_ctl 带 -D 数据目录前台启动错误会直接打到控制台确认服务端健康之前不要调客户端超时参数。我在现场见过最冤的一次排查同事花了半天调 Npgsql 超时最后发现是数据库服务器磁盘满了日志第一行就写着 could not write to file: No space left on device。5. 把连接用稳COPY 批量导入、Dapper 封装与参数化边界5.1 NpgsqlBinaryImporter用 COPY 协议批量导数据数据初始化或同步场景几万行起步的数据如果一条条 INSERT再快的连接池也救不了。Npgsql 3.x 提供了 BeginBinaryImport直接走 PostgreSQL 的 COPY 二进制协议批量插入速度能比逐条 INSERT 快一个数量级。connString 就用 3.1 节那一串最小用法如下using (var conn new NpgsqlConnection(connString)) { conn.Open(); using (var writer conn.BeginBinaryImport( COPY import_tmp (id, name, amount) FROM STDIN WITH (FORMAT BINARY))) { for (var i 0; i 100000; i) { writer.StartRow(); writer.Write(i, NpgsqlDbType.Integer); // int4 writer.Write(name_ i, NpgsqlDbType.Text); // text writer.Write(i * 1.5m, NpgsqlDbType.Numeric); // numeric } writer.Complete(); // 提交这批数据 } }逻辑说明StartRow 开始一行Write 按目标表列的顺序写入带 NpgsqlDbType 的重载避免类型歧义。如果循环里出异常不要调用 Complete直接 Dispose 即中止本次 COPY服务端会丢弃这批数据。为了重跑安全我一般先 COPY 到临时表 import_tmp全部成功后再 INSERT INTO 正式表 SELECT失败就 DROP不给脏数据留机会。注意 COPY 的列顺序必须和 SQL 里写的一致少一列或换顺序都在服务端报错这个报错时间点比较晚出错时只能逐列对照。5.2 Dapper Npgsql最小封装与参数传递如果不想在业务代码里反复写 NpgsqlCommandDapper 是 .NET Framework 4.5 项目最省事的封装层。它和 Npgsql 的配合没有额外配置只要连接串和 provider 正确using (var conn new NpgsqlConnection(builder.ConnectionString)) { var users conn.QueryUser( SELECT id, name FROM users WHERE created_at since ORDER BY id LIMIT limit;, new { since DateTime.UtcNow.AddDays(-7), limit 100 }).ToList(); }Dapper 会把匿名对象的属性名转成参数名和 Npgsql 的命名参数对齐。这里有一个组合坑如果一条 SQL 里同一个参数名出现两次部分老版本 Dapper 加 Npgsql 3.x 会报 parameter not found稳妥做法是拆成两个参数名since1 和 since2在代码里赋同样的值。另一个坑是匿名对象掉进了看似参数化其实是拼串的陷阱Dapper 的 Query 重载如果第二个参数传的是字符串会被当作命令文本的一部分处理务必传对象而不是字符串。5.3 参数化、事务与 EF6 的历史包袱参数化的核心是显式类型。AddWithValue 能省代码但遇到 numeric 列和 decimal 精度、timestamp 和 timestamptz 这种敏感类型时推断结果不一定符合预期。显式写法是cmd.Parameters.Add(new NpgsqlParameter(amount, NpgsqlDbType.Numeric) { Value 1234.56m });事务方面老项目里最常见的错误是忘记给命令对象赋值事务using (var tx conn.BeginTransaction()) { using (var cmd new NpgsqlCommand( UPDATE account SET balance balance - amount WHERE id id;, conn, tx)) { cmd.Parameters.AddWithValue(amount, 100m); cmd.Parameters.AddWithValue(id, 42); cmd.ExecuteNonQuery(); } tx.Commit(); }NpgsqlCommand 的构造函数第三参数接收事务漏了它命令会在无事务状态下执行异常时不回滚排查时特别隐蔽。如果你在 .NET Framework 4.5 项目里还挂着 EF6配套的 provider 是 EntityFramework6.Npgsql版本要跟上 Npgsql 3.2.7装完必须检查 app.config 里 DbProviderFactories 有没有注册成功否则运行时报 The provider is not registered。说实话EF6 加 PostgreSQL 的历史包袱不小新代码我一般劝退直接 Dapper 或裸 ADO.NET 反而清爽。与 MySQL 的差异也提醒一句PostgreSQL 的占位符不区分 和 :不支持 MySQL 的反引号分页用 LIMIT / OFFSET自增主键用 serial 或 identity迁移 SQL 时别只改连接串。6. 把版本号和连接状态写进日志一个能救命的检查习惯这个技巧不复杂但救过我两次。启动时打印 Npgsql 程序集版本和服务端版本排障先看这两行public static void LogConnectionInfo(string connString) { var asm typeof(NpgsqlConnection).Assembly; Console.WriteLine(Npgsql Assembly: asm.FullName); using (var conn new NpgsqlConnection(connString)) { conn.Open(); using (var cmd new NpgsqlCommand(SELECT version();, conn)) { Console.WriteLine(PG Server: cmd.ExecuteScalar()); } } }把程序集名、程序集版本、server_version 三个输出打进日志头再顺手查一下 pg_stat_activity 里当前连接的 state。我吃过一次亏线上问题查了两天最后发现 bin 里躺着一个 2.x 的 Npgsql.dll日志第一行如果当时就打印了版本一眼就能看穿。后来我把这个方法塞进连接工厂每次升级 Npgsql、迁移服务器、切换 PostgreSQL 大版本前先跑一遍确认客户端和服务端都在预期范围内再看业务。这个习惯的成本是一次启动日志的输出收益是省掉无数个莫名其妙的连不上。希望帮到你。本文还有配套的精品资源点击获取