简介面向.NET Framework 4.0平台的PostgreSQL数据库连接器供使用C#、VB.NET等语言并通过ADO.NET接口进行数据操作的开发者使用。压缩包包含Npgsql.dll主库、Entity Framework及Legacy支持库、Mono.Security.dll安全组件并提供多语言资源文件可满足连接、查询、事务、ORM映射及加密通信等场景。整体共19个文件以dll库为主配以pdb调试符号、xml接口文档、config配置及文本说明压缩包大小仅681KB十分轻量部署方便。已有199人学习下载适合中小型项目快速集成也适用于维护基于.NET Framework 4.0的旧系统。该版本内含README.md配置指引和LICENSE.txt开源协议便于理解使用条款pdb文件配合Visual Studio可实现源码级调试xml文档辅助快速查阅API。打包内容完整省去自行编译与兼容性验证的麻烦是.NET Framework 4.0环境下连接PostgreSQL的实用选择。1. Npgsql-2.2.4.3-net40一台只剩 .NET 4.0 的老服务器绕不开它的场景收到一个叫 Npgsql-2.2.4.3-net40.zip 的包多半不是在装新系统而是在救一台跑着 .NET 4.0 的旧机器。这个包是 PostgreSQL 生态里历史悠久的 .NET 数据驱动 Npgsql 的 2.2.4.3 版本net40 后缀说明它面向 .NET Framework 4.0CLR 4.0编译。它的作用很直接让老 C#、VB.NET 程序用 ADO.NET 的 Connection、Command、DataReader 直接读写 PostgreSQL不装数据库客户端也不依赖中间件。需要它的人基本是同一类数据库从 Oracle、MSSQL 迁到 PostgreSQL但业务程序被历史包袱锁死在 .NET 4.0 上。新版 Npgsql 动不动要求 .NET 4.6.2 甚至更高卡在 4.0 上的项目能用的备选不多这个老包就成了最顺手的一条路。别以为新驱动一定比老驱动好用在受限环境下老版本带来的确定性反而最宝贵。2. 把 zip 变成可用引用net40 目录、dll 引用与目标框架的匹配拿到这个 zip先别急着在 Visual Studio 里双击或解压。老版本 Npgsql 的发布包习惯把多个目标框架的编译产物放一起解压后很可能看见 net20、net35、net40 这样的子目录有的还带 net45。搞清楚这些目录的含义再动手能少走很多弯路。2.1 解压后的常见形态net20、net35、net40 这些目录在说什么Npgsql 用同一套源码为不同版本 .NET 编译net40 目录下的程序集引用的是 .NET Framework 4.0 的运行时和基础类库由 Visual Studio 2010 及之后的编译器生成。这里有个容易混淆的点net40 程序集能运行在后续的 .NET Framework 4.5、4.6、4.8 上因为 Framework 是向后兼容的反过来net35 的程序集想跑在 4.0 进程里通常也可以但官方发布时把它们单独分目录就是提醒你别拿错。真实的 zip 里不会只有 Npgsql.dll 一个文件2.2.x 时代它往往还带着依赖的辅助程序集比如处理 SSL 连接或安全相关逻辑时需要用到的部分。很多人只把主 dll 拷走剩下的一律不理会结果程序跑起来后在某个功能点突然抛程序集加载异常那时候再回想是哪个 dll 没到位排查成本就高了。我一般会把整个 net40 目录原样复制到项目的第三方库目录再按目录去引用而不是只挑一个 Npgsql.dll。2.2 为什么我不用 NuGet 而用 zip 引用离线环境下的可控性你可能想问为什么不用 Package Manager Console 敲一条 Install-Package Npgsql -Version 2.2.4.3机器能连外网的话NuGet 确实更方便。但真实用到这个包的环境多数是连不了外网或者被安全策略锁住的业务内网不允许访问 NuGet 源也不让随便装新软件。zip 方式在内网里是最老实的做法拷进去就能用不动全局程序集缓存不写系统配置卸载时直接删目录干净利落。手动引用的步骤很固定第一步在解决方案里建一个第三方依赖目录比如叫 libs/Npgsql/net40。第二步把解压出的 net40 目录里所有文件复制进去。第三步在 VS 里右键项目引用选“添加引用”切到“浏览”页签定位到刚才复制的位置选 Npgsql.dll。第四步把该引用的“复制本地”属性设为 true。这个属性非常关键它决定编译后 dll 会不会自动进到 bin 目录发布时少带一个文件生产环境就会用报错来提醒你。2.3 平台位数与目标框架net40 不是“随便跑”的万能包net40 描述的是 .NET 运行时版本不是 CPU 平台。老项目里默认配置通常是 AnyCPU但很多实际部署环境已经被外部组件限死了位数比如某个老 COM 控件只有 32 位版本IIS 应用池被迫开了“启用 32 位应用程序”。这时候如果连接串和代码都没问题驱动却在 Open 时抛 BadImageFormatException很多人第一反应是 Npgsql.dll 损坏重新解压、重新引用折腾几小时后发现完全没用。正确做法是先把进程的位数问题确定下来项目配置管理器的活动解决方案平台是 x86 还是 x64部署的 IIS 应用池是否启用了 32 位Windows 服务有没有设置平台标记。Npgsql.dll 的位数跟着进程走不是独立决定因素。遇到 BadImageFormatException先查平台匹配再查文件完整性顺序反了就是浪费时间。3. 连上 PostgreSQL连接字符串、参数化查询与最小可跑示例引用配好后下一步是让驱动真正把网络打通。Npgsql 从 2.x 到 4.x命令对象的使用方式变化不大老代码迁到新驱动时改的主要是连接字符串和个别类型映射。这里先把 2.2.4.3 的常见连接参数讲清楚再给一段能立即验证连通性的代码。3.1 连接字符串Server、Port、Database 与 SSL 的写法Npgsql 的连接字符串长得和 SQL Server 很像但参数名有差别。最容易让数据库迁移过来的人写错的就是 Database有人习惯写 Initial Catalog。在 Npgsql 里只认 Database。下面是一段我常用的最小连接串string connStr Server192.168.10.20;Port5432;Databaseerpdb;User Idapp_user;PasswordYourPass;Poolingtrue;MinPoolSize1;MaxPoolSize50;SslModeDisable;;这串参数里Server 也可以写成 Host两种写法在老版本里都认。Port 不写时默认是 5432只要机器上装了多个 PostgreSQL 实例或者发生过连错库的事件我就要求必须显式写出来不给隐患留空间。User Id 和 Password 注意大小写敏感PostgreSQL 的用户名和密码不像 SQL Server 那样可以模糊处理。Pooling 控制连接池开关MinPoolSize 和 MaxPoolSize 决定池的弹性。老驱动默认开了池但默认上限在业务量增长后往往不够。SslMode 在老版本里和 SSL 混着用内网环境我一般直接设 SslModeDisable避免 TLS 协议版本不一致带来的握手问题外网或安全要求高的环境则要按公司规范升级驱动不能只靠这个老包硬扛。3.2 最小可跑代码从 Open 到 select version()引用配好后先用最短代码验证链路通不通。这段代码我几乎每次接老项目都会先跑一遍确认网络、端口、用户名密码、数据库名这四个要素都没问题再进入业务逻辑。using System; using Npgsql; class QuickTest { static void Main(string[] args) { string connStr Server127.0.0.1;Port5432;Databasetest;User Idpostgres;Password123456;Poolingtrue;; using (NpgsqlConnection conn new NpgsqlConnection(connStr)) { conn.Open(); using (NpgsqlCommand cmd new NpgsqlCommand(select version();, conn)) { string version (string)cmd.ExecuteScalar(); Console.WriteLine(version); } } } }逻辑说明NpgsqlConnection 负责建立到 PostgreSQL 的物理连接Open 之后连接才真正可用。select version() 返回的是数据库版本字符串ExecuteScalar 取第一行第一列所以可以强转成 string 后直接输出。如果这条能打出版本号说明驱动、网络、认证三个环节都通了。这里我特意在外层 using 里创建连接因为 using 到作用域结束会自动 Close这是保证连接归还连接池最省心的姿势。参数说明连接字符串里的 Server 指向 PostgreSQL 所在主机本地测试写 127.0.0.1不走 Unix Socket。Port 默认 5432显式写出更清楚。CommandTimeout 没有设置时按驱动默认值走老版本默认一般是 20 秒生产环境大查询要按需调大这个后面避坑部分再说。3.3 参数化写入NpgsqlParameter 与 RETURNING id连接通了就要碰业务。老项目里最常见的坏习惯是把变量直接拼进 SQL 字符串比如 “select * from t where id” userId。这么做在今天任何数据库上都是高风险动作Npgsql 提供了完整的参数化接口用起来不复杂只是占位符风格和 SQL Server 有差异。int userId; using (NpgsqlConnection conn new NpgsqlConnection(connStr)) { conn.Open(); const string sql INSERT INTO app_user(user_name, email) VALUES(:name, :mail) RETURNING id;; using (NpgsqlCommand cmd new NpgsqlCommand(sql, conn)) { cmd.Parameters.Add(new NpgsqlParameter(name, NpgsqlDbType.Text) { Value 张伟 }); cmd.Parameters.Add(new NpgsqlParameter(mail, NpgsqlDbType.Text) { Value zwexample.com }); userId (int)cmd.ExecuteScalar(); } }逻辑说明SQL 里的 :name 和 :mail 是参数占位符NpgsqlParameter 对象把它们替换成安全值后再发给 PostgreSQL值和 SQL 文本分离注入从机制上被挡住了。RETURNING id 是 PostgreSQL 的特色语法插入后直接把自增主键返回省掉再查一次 sequence 的请求这在 2.2.4.3 时代是最好用的拿主键姿势。参数说明NpgsqlDbType.Text 对应 PostgreSQL 的 text/varchar 类型。Value 赋的是 .NET 字符串。构造参数时第一个参数名不带冒号Npgsql 会拿 SQL 里的占位符做匹配。这里有个养成习惯同一句 SQL 里参数前缀要么全用冒号要么全用 混着用容易触发老驱动的解析歧义后面避坑章节单独讲。提示如果你是从 SQL Server 迁移过来的最容易踩的就是占位符 和冒号 : 混用统一成一种风格再上线。4. Npgsql 2.2.4.3 避坑指南五个真实翻车点的现象、原因与当场处理老驱动不是不能用而是要知道它的边界。下面五个坑是我把 Npgsql 2.x 接到存量项目时实际遇到最多的按现象、原因、解决的顺序写你可以直接对照排查。4.1 程序集加载失败Npgsql.dll 明明在 bin 里Open 却报加载异常现象编译能通过运行到 new NpgsqlConnection 或 conn.Open() 时抛出 System.IO.FileNotFoundException看异常信息是 Npgsql.dll 找不见打开 bin 目录dll 明明就在那里。原因最常见的是引用的 Npgsql.dll 在项目里属性“复制本地”为 falsepublish 或 build 后 bin 目录里那个 dll 是旧版本拷贝或者压根没拷进去。另一种情况是项目同时引用了另一个组件那个组件传递引用了更新版本的 Npgsql运行时按新版本去绑定自然找不到 2.2.4.3。解决先在项目引用里查 Npgsql 的“复制本地”属性设为 true 后重新生成。再看解决方案里是否还有其他引用间接带入了 Npgsql有的话要么统一版本要么用 app.config 里的 bindingRedirect 把版本号全部指向 2.2.4.3。这一步做干净加载异常基本消失。4.2 SSL 握手通不过老驱动连新 PostgreSQL 的 TLS 问题现象连接串里写了 SslModeRequire 或 SSLtrue程序在 Open 时报错要么是握手超时要么是服务器端拒绝了 TLS 版本偶尔表现为连接一直卡住直到超时才抛异常。原因Npgsql 2.2.4.3 是十多年前的版本当时 TLS 的主流协议还是 1.0/1.1。新 PostgreSQL 部署时通常已经关闭了这些老协议强制要求 TLS 1.2 以上两边协商不到共同版本握手就断了。解决内网环境最直接的办法是连接串改成 SslModeDisablePostgreSQL 服务端不用 SSL双方用明文连接。前提是网络链路本身可控。如果公司安全策略不允许明文那这条路走不通正确选择是升级到支持新 TLS 的 Npgsql 版本而不是继续在这个老包上纠结。我见过硬编 TLS 底层参数和系统注册表去兼容老驱动的做法那是拿生产环境的安全换旧代码的懒惰不建议碰。4.3 时间字段差 8 小时timestamp 与 timestamptz 的时区偏移现象从 PostgreSQL 读出来的时间比数据库里存的值多几个或少几个小时。更诡异的是某些列正常某些列偏移对比半天也找不到规律最后被人当成玄学。原因Npgsql 2.x 年代timestamp without time zone 和 timestamp with time zone 的映射策略并不像今天这么严格。timestamptz 读取时会按服务器时区转成 .NET 的 DateTime如果应用机器和数据库机器的时区设置不一致或者 PostgreSQL 的 timezone 参数不是 UTC转换后就会出现偏移。解决把时区的事放在数据库连接层统一掉在连接初始化时执行 set timezone‘UTC’再让应用层全部按 UTC 处理显示层再转本地。代码里对时间的比较、分组也统一用 UTC 值。如果只是展示让前端转换如果是业务计算必须固定基准。这一条不光是 Npgsql 的问题任何数据库驱动都适用。4.4 参数前缀混用一条 SQL 里既有 又有 :参数对不上现象SQL 写成 select * from t where idid and name:name代码里 Parameters 也加了两个但运行时不是报“列不存在”就是报“运算符不存在: text integer”怎么检查都看不出错。原因Npgsql 老版本对参数前缀的解析并不是简单地把每种前缀都转成同名参数它有自己的匹配规则混用冒号和 时第二、第三个参数很有可能没有被正确替换PostgreSQL 收到的 SQL 带着未解析的文本自然报错。解决一条 SQL 里只用一种前缀我自己的习惯是统一用冒号。代码里所有参数名不带前缀NpgsqlParameter 构造时也不带前缀让驱动自己匹配。团队写 SQL 时把这条写进规范问题就不再复发。4.5 连接池被耗尽旧代码把连接开在 using 外面现象程序运行几个小时后新请求打开连接时开始等待慢慢变成超时异常错误信息里有 connection pool 字样。重启应用后恢复过几小时又挂在同样位置。原因连接池有上限连接打开后没被归还。典型场景是代码里 new NpgsqlConnection 之后忘了 Closereturn 之前 if 分支里提前跳出或者 DataReader 读取中断但没有关闭连接。池里的连接被占满新请求只能排队等超时。解决所有连接都放进 using 里NpgsqlCommand 和 NpgsqlDataReader 同样用 using。DataReader 只要没读完底层连接就会被占住所以读取循环结束后要显式 reader.Close() 或直接用 using 包住。已经在生产的系统排查时先查代码里有没有 new NpgsqlConnection 后没有配套 Close 的地方这种问题往往几十行代码就能看出病根。5. 一个快速的验证习惯在 PostgreSQL 端开执行日志反查驱动行为接手 Npgsql 老项目时我第一件事往往不是读代码而是先确认数据库端到底收到了什么。驱动对开发者来说像个黑匣子连接串参数写错、SQL 被参数化处理成什么样、实际用的数据库是不是你以为的那个答案都在 PostgreSQL 的服务端日志里。5.1 打开执行日志确认驱动发出的真实 SQL在 psql 里执行下面两行让 PostgreSQL 把所有语句都记下来ALTER SYSTEM SET log_statement all; SELECT pg_reload_conf();ALTER SYSTEM 是 9.4 之后才有的写法老版本直接改 postgresql.conf 里的 log_statement 再 reload 也一样。log_statementall 会把每条收到的 SQL 写进日志包括参数化语句的预处理结果。然后去看 PostgreSQL 日志目录下的文件Linux 环境常见在数据目录的 log/ 下或者 /var/log/postgresql/ 下按实际安装路径找。日志里能看到来自 Npgsql 的连接是从哪个 IP 发起的执行了什么 SQL查询有没有走到预期数据库。有一个很经典的错位场景就是项目配置里 Database 写错应用启动不报错读到的却是另一套初始化数据查业务代码查一天都查不出来日志一开连接库明明白白写在里面。验证完记得把 log_statement 设回 none尤其生产库全部日志会把磁盘打满。这一步几乎零成本却是判断问题属于驱动还是属于数据库的最快路径。这几年我把它当成接 Npgsql 老项目的第一步而不是翻代码几次都直接锁定了问题。希望帮到你。本文还有配套的精品资源点击获取
