老框架连PostgreSQL：两个DLL搞定Npgsql与Mono.Security

简介面向 .NET Framework 4.5 环境下需要连接 PostgreSQL 数据库的开发者这份资源提供了 Npgsql 数据访问组件及配套依赖的完整程序集可解决旧版框架中缺少官方驱动、SSL 加密支持不足的问题。压缩包共 19 个文件约 726KB以 dll 动态库为主辅以 pdb 调试符号、xml 文档注释、config 配置文件和 README 说明涵盖 Npgsql 核心库、Entity Framework 适配器以及 Mono.Security 加密组件便于直接引用与调试排错。已有 895 人学习下载。资源中 Npgsql 提供 ADO.NET 兼容接口支持查询、事务、参数化命令与类型映射Mono.Security 则承担 X.509 证书与 SSL 连接验证适合需要安全传输的数据库项目。借助 Entity Framework 适配器读者还能以 ORM 方式操作 PostgreSQL减少手写 SQL 的工作量是维护旧版 .NET 项目时较实用的参考包。1. 老项目连 PostgreSQL为什么我最后只留了两个 DLL前阵子接手一个跑在 .NET Framework 4.5 上的老系统需求很简单把数据从 SQL Server 挪到 PostgreSQL。听起来是换个连接字符串的事真动手才发现坑不少——机器上装不了新版驱动NuGet 拉下来的包又依赖一堆新运行时编译能过、一跑就炸。折腾半天最后稳定下来的方案朴素得有点反直觉只往项目里丢两个 DLLNpgsql.dll负责 PostgreSQL 协议通信Mono.Security.dll补上老框架缺失的加密能力引用一加连接、查询、事务全通。这套组合特别适合还在维护 .NET Framework 4.5/4.6 存量项目、又必须接 PostgreSQL 的开发者尤其是那些不能随便升级运行时、只能靠文件引用解决问题的场景。下面我按「这俩 DLL 到底干什么 → 怎么引进去跑通 → 怎么改造成自己能用的封装」的顺序把这份资源拆开讲清楚。2. 两个 DLL 的分工Npgsql 与 Mono.Security 各管什么2.1 Npgsql 在 .NET Framework 下的角色Npgsql是 .NET 生态里访问 PostgreSQL 的事实标准驱动它实现了 ADO.NET 那套接口NpgsqlConnection、NpgsqlCommand、NpgsqlDataReader、NpgsqlTransaction用法和SqlClient几乎一一对应。对老框架项目来说它的价值在于不依赖 .NET Core 那套新运行时直接以程序集形式被System.Data体系接纳。你写using Npgsql;之后代码风格和写 SQL Server 时没有割裂感团队里熟悉 ADO.NET 的人几乎零学习成本。需要留意的是版本匹配。.NET Framework 4.5 对应的 Npgsql 版本不能太新常见做法是选 3.x 或 4.x 早期版本这些版本的目标框架包含net45直接文件引用即可。太新的 5.x/6.x 大量依赖netstandard2.0及以上在老项目里引用会出现「找不到程序集或依赖」的连锁报错。这份资源给的就是能直接落地的那一档省去了自己试版本的时间。2.2 Mono.Security 补的是哪块短板很多人第一次看到Mono.Security.dll会疑惑连个数据库为什么要扯上 Mono原因在加密。PostgreSQL 支持多种认证方式其中md5和scram-sha-256是主流而 .NET Framework 4.5 自带的加密库对某些哈希、证书链校验的支持并不完整尤其在处理 SCRAM 认证的 PBKDF2 派生、以及 SSL 连接时的证书验证环节容易抛NotSupportedException或握手失败。Mono.Security提供了这些缺失的加密原语实现Npgsql 在运行时按需调用它。所以这两个 DLL 是配套关系不是二选一。只放Npgsql.dll在密码认证较严或要求 SSL 的库上大概率连不上两个都放认证和加密链路才完整。我一般会把它们放在项目根目录下的libs/文件夹而不是散在bin里方便后续换版本时统一管理。2.3 引用方式与目标框架确认文件引用的关键是把「复制到本地」打开否则调试时能跑、发布后缺 DLL。下面是我在项目里常用的引用配置写法.csproj片段比在 IDE 里点鼠标更可控也方便进版本库ItemGroup !-- 两个程序集都设为私有复制保证发布目录带上 -- Reference IncludeNpgsql HintPathlibs\Npgsql.dll/HintPath PrivateTrue/Private /Reference Reference IncludeMono.Security HintPathlibs\Mono.Security.dll/HintPath PrivateTrue/Private /Reference /ItemGroupHintPath指向相对路径团队协作时不会因为某人机器上的绝对路径不同而失效PrivateTrue等价于属性面板里的「复制到本地」是发布不丢 DLL 的保险。改完记得确认项目的目标框架确实是.NET Framework 4.5在「属性 → 应用程序 → 目标框架」里核对框架选错会直接导致程序集加载失败。3. 跑通第一条连接连接字符串、查询与事务3.1 连接字符串的组成与常见参数先把连接跑通再谈封装。PostgreSQL 的连接字符串和 SQL Server 思路一致但键名不同写错一个键就是超时或认证失败。下面这段是我验证过能用的最小配置// 最小可用连接串Host/Port/Database/Username/Password 是核心五项 string connStr Host127.0.0.1; // 数据库地址远程填 IP 或域名 Port5432; // 默认端口改过就跟着改 Databaseappdb; // 目标库名 Usernameappuser; // 登录角色 Password******; // 密码生产环境别硬编码 Timeout15; // 建立连接超时秒 CommandTimeout30; // 单条命令执行超时秒 Poolingtrue; // 开启连接池老项目必开 SSL ModePrefer; // 优先 SSL服务端不支持则回落Timeout和CommandTimeout是两个不同的东西前者管「连不上」后者管「连上了但查询慢」排查问题时先分清是哪一个超时能省很多时间。SSL Mode在 3.x/4.x 里取值有Disable/Prefer/Require内网库常用Prefer要求强制加密就上Require此时Mono.Security的作用就体现出来了。密码不要写死在代码里常见做法是放配置文件或环境变量这里为了演示才内联。3.2 一次完整的增删改查代码连接通了之后把 ADO.NET 那套流程走一遍确认驱动行为符合预期。下面这段覆盖参数化查询、读取和写入是后续封装的地基using Npgsql; using System; public class PgDemo { private readonly string _connStr; public PgDemo(string connStr) { _connStr connStr; } // 查询参数化避免注入DataReader 逐行读 public void QueryUser(int userId) { using (var conn new NpgsqlConnection(_connStr)) { conn.Open(); using (var cmd new NpgsqlCommand( SELECT id, name, created_at FROM users WHERE id id, conn)) { cmd.Parameters.AddWithValue(id, userId); // 参数占位符用 using (var reader cmd.ExecuteReader()) { while (reader.Read()) { Console.WriteLine(${reader.GetInt32(0)} ${reader.GetString(1)} ${reader.GetDateTime(2)}); } } } } } // 写入返回受影响行数判断是否成功 public int InsertUser(string name) { using (var conn new NpgsqlConnection(_connStr)) { conn.Open(); using (var cmd new NpgsqlCommand( INSERT INTO users(name, created_at) VALUES(n, now()), conn)) { cmd.Parameters.AddWithValue(n, name); return cmd.ExecuteNonQuery(); } } } }参数占位符是名字和 SQL Server 一致但 PostgreSQL 原生用的是$1这种位置参数Npgsql 帮你做了转换所以按写就行。using包住连接和命令是必须的连接池靠Dispose归还连接漏掉就会池耗尽。reader.GetInt32(0)这类按序号取值比按列名快但列顺序变了容易错团队里我一般要求按列名取牺牲一点性能换可维护性。3.3 事务与批量写入单条语句没问题后事务是绕不开的。PostgreSQL 的事务语义和 SQL Server 接近但要注意NpgsqlTransaction必须显式Commit异常时Rollbackpublic void Transfer(int fromId, int toId, decimal amount) { using (var conn new NpgsqlConnection(_connStr)) { conn.Open(); using (var tx conn.BeginTransaction()) // 开启事务 { try { using (var cmd new NpgsqlCommand( UPDATE accounts SET balance balance - a WHERE id id, conn, tx)) { cmd.Parameters.AddWithValue(a, amount); cmd.Parameters.AddWithValue(id, fromId); cmd.ExecuteNonQuery(); } using (var cmd new NpgsqlCommand( UPDATE accounts SET balance balance a WHERE id id, conn, tx)) { cmd.Parameters.AddWithValue(a, amount); cmd.Parameters.AddWithValue(id, toId); cmd.ExecuteNonQuery(); } tx.Commit(); // 两步都成功才提交 } catch { tx.Rollback(); // 任一步失败整体回滚 throw; } } } }NpgsqlCommand的构造函数第三个参数传事务对象这一步不能省否则命令不在事务上下文里回滚对它无效。批量写入场景下逐条ExecuteNonQuery在数据量大时会很慢常见做法是拼多值INSERT或使用COPY但COPY在 3.x 版本里 API 有差异改造前先确认手里的 Npgsql 版本支持哪种写法。4. 避坑与排查老框架连 PostgreSQL 的五个血泪经验4.1 报「无法加载文件或程序集 Npgsql」现象是编译通过运行时抛FileNotFoundException或Could not load file or assembly。原因通常是Private没开或者发布时libs/下的 DLL 没被复制到输出目录。解决方式是检查.csproj里PrivateTrue并确认发布配置里没有排除该文件如果用了安装包制作工具还要单独把两个 DLL 加进打包清单。4.2 认证失败password authentication failed现象是连接直接被拒日志里是认证错误。原因多半是服务端pg_hba.conf要求的认证方式如scram-sha-256与驱动版本不匹配或者Mono.Security.dll缺失导致加密派生失败。解决方式是先确认两个 DLL 都在再核对服务端认证配置如果服务端强制 SCRAM 而驱动版本偏老常见做法是让 DBA 为该用户临时放开md5或升级到支持 SCRAM 的 Npgsql 版本。4.3 SSL 握手报证书链错误现象是SSL ModeRequire时抛证书验证异常。原因是老框架的证书校验链不完整或服务端用的是自签证书。解决方式分两种生产环境把服务端 CA 证书导入受信任根测试环境临时用SSL ModePrefer或配置Trust Server Certificatetrue视版本支持情况但生产别这么干等于关掉了加密校验。4.4 连接池耗尽程序卡死现象是运行一段时间后所有请求挂起日志显示等待连接。原因是某处NpgsqlConnection没Dispose连接没归还池。解决方式是全局排查new NpgsqlConnection是否都在using里或者用try/finally显式Close另外把MaxPoolSize设一个合理值别用默认无限增长出问题时更容易定位。4.5 中文乱码或时间字段错位现象是查出来的中文变问号或timestamp读出来差几个小时。原因是数据库编码不是 UTF8或服务端时区与客户端不一致。解决方式是建库时确认ENCODINGUTF8时间字段统一用timestamptz并在连接串里显式设置时区读取时用GetDateTime而不是字符串转换避免格式歧义。5. 二次开发把裸驱动包成项目能用的数据访问层5.1 封装思路从散落代码到统一入口裸用NpgsqlConnection写业务代码里会到处是连接字符串和using改一个库地址要翻遍全项目。我一般的做法是抽一个轻量数据访问层一个PgHelper管连接创建一个PgRepository管具体表的读写业务层只依赖接口。这样换驱动版本、加日志、加重试都只改一处。下面是一个最小骨架public interface IDbConnectionFactory { NpgsqlConnection Create(); // 统一出口便于替换与测试 } public class PgConnectionFactory : IDbConnectionFactory { private readonly string _connStr; public PgConnectionFactory(string connStr) { _connStr connStr; } public NpgsqlConnection Create() { var conn new NpgsqlConnection(_connStr); conn.Open(); // 也可延迟到使用时再开 return conn; } }工厂模式的好处是连接字符串只在一个地方出现单元测试时可以换成指向测试库的实现。Create()里直接Open还是延迟打开取决于你的调用习惯我倾向延迟让调用方用using控制生命周期避免工厂返回一个已打开却没人关的连接。5.2 加一层重试与日志老系统网络抖动是常态给关键查询加简单重试能显著降低偶发失败率。注意只对「可重试」的异常重试比如连接超时别对语法错误重试public T ExecuteWithRetryT(FuncNpgsqlConnection, T action, int maxRetry 3) { for (int i 0; i maxRetry; i) { try { using (var conn _factory.Create()) return action(conn); } catch (NpgsqlException ex) when (i maxRetry - 1 IsTransient(ex)) { Thread.Sleep(200 * (i 1)); // 退避避免瞬间打满 } } throw new InvalidOperationException(重试次数耗尽); } // 只把连接类异常视为可重试业务异常直接抛 private bool IsTransient(NpgsqlException ex) { return ex.InnerException is System.Net.Sockets.SocketException || ex.Message.Contains(timeout); }maxRetry别设太大3 次足够覆盖大多数抖动设多了反而拖长故障响应时间。退避用200 * (i 1)毫秒是简化写法生产里可以换成指数退避。IsTransient的判断依据要按你实际遇到的异常类型调整这里给的是常见起点。5.3 验证改造是否成功的三个检查点改完之后别急着上线我一般跑三个检查一是把连接字符串指向一个不存在的库确认程序在合理时间内报错而不是卡死二是并发压一下查询接口看连接池是否稳定归还三是故意断网再恢复验证重试逻辑生效且没有重复写入。这三点过了基本能放心。下面这张表是我常用的验证清单改造时对着勾检查项操作预期结果连接失败改错 Host15 秒内抛连接异常连接池并发 50 请求无连接泄漏池计数回落重试中途断网自动重试后成功或明确报错事务制造中途异常数据整体回滚无脏写5.4 一个具体技巧用配置文件驱动连接参数最后分享一个我踩过坑才养成的习惯连接参数全部走配置文件代码里只读不写。早期图省事把连接串写进常量结果测试库和正式库切换时改漏一处数据写错了库排查了大半天。从那以后我每次接新库都强制走一遍「配置读取 → 工厂创建 → 冒烟查询」的流程确认参数来源唯一。配置文件里把Host、Database、SSL Mode分开写比一整串连接字符串更好维护也方便不同环境用不同配置节覆盖。这套两个 DLL 加一层薄封装的组合在 .NET Framework 4.5 的老项目里足够稳改造时按上面的检查点走一遍基本不会翻车。希望帮到你。本文还有配套的精品资源点击获取