企业官网建设流程全解析

简介：面向在 .NET Framework 4.5 环境下开发 PostgreSQL 应用的开发者，这份资源提供了可直接引用的数据库连接组件集合，重点解决旧版框架中 Npgsql 数据访问与安全加密依赖的配套问题。压缩包共 19 个文件、约 726KB，以 dll 动态库为主体，辅以 pdb 调试符号、xml 文档注释、config 配置及 README 说明，覆盖 Npgsql 核心库、Entity Framework 与 Legacy 适配器以及 Mono.Security 安全组件，便于按项目需要取用。已有 895 人学习下载，说明其在旧框架迁移与维护场景中具有一定参考价值。读者可借此快速搭建 ADO.NET 风格的连接与命令调用，理解参数化查询、事务与类型映射的用法，并通过 Entity Framework 适配器简化对象关系映射；同时可结合调试符号定位异常、依据许可协议合规使用，减少版本兼容与 SSL 连接验证方面的摸索成本。

1. 老项目连 PostgreSQL：为什么 .NET Framework 4.5 上最容易翻车的不是数据库而是驱动

上周帮一个做内部管理系统的朋友收拾一台老服务器，机器上跑着 .NET Framework 4.5 的 Web 应用，数据库是 PostgreSQL。业务代码一行没改，只是把数据库从测试环境切到生产环境，应用启动就报System.IO.FileLoadException，提示找不到Mono.Security的某个版本。折腾了两个小时才定位到：项目里引用的Npgsql.dll版本和Mono.Security.dll版本不匹配，一个是 NuGet 拉下来的新版，一个是同事从别的项目目录里直接拷过来的旧文件。

这个场景在维护老系统的团队里太常见了。.NET Framework 4.5 是 2012 年的运行时，很多新版本 Npgsql 早就把最低框架要求提到了 4.6.1 甚至更高，直接装最新版必然在编译期或运行期炸掉。而 PostgreSQL 的连接又不像 SQL Server 那样有微软官方驱动兜底，选错版本、配错依赖，表现出来往往是连接超时、SSL 握手失败、程序集加载异常这类看着像网络问题的玄学故障。这篇笔记记录的是我在 .NET Framework 4.5 环境下把 Npgsql 和 Mono.Security 这套连接 API 装通、配好、验证跑通的完整过程，适合还在维护老框架项目、需要连 PostgreSQL 的开发者照着走一遍。

2. 环境与版本选型：Npgsql 和 Mono.Security 到底该配哪一版

2.1 先确认运行时和目标框架，别急着下载

动手之前先把机器上的运行时情况摸清楚，这一步决定了后面能选哪个版本的驱动。.NET Framework 4.5 和 4.5.1、4.5.2 在程序集绑定行为上有细微差别，尤其是强名称程序集的版本重定向，配错了会在运行时才暴露。

打开目标机器，用下面这条命令确认已安装的 .NET Framework 版本：

# 查询注册表中已安装的 .NET Framework 版本（含 4.x 系列） reg query "HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full" /v Release

Release的值对应关系需要记一下：378389 是 4.5，378675 是 4.5.1，379893 是 4.5.2，393295 及以上才是 4.6。如果查出来是 378389，那这台机器就是纯 4.5，后面选驱动必须严格按 4.5 的兼容性来。我一般还会顺手看一眼%WINDIR%\Microsoft.NET\Framework64\v4.0.30319目录下的clr.dll文件版本，双重确认，避免注册表被改过但实际运行时没装全的情况。

确认完运行时，再打开项目的.csproj文件，看<TargetFrameworkVersion>节点写的是v4.5还是v4.5.1。这两个值在 Visual Studio 里看起来差不多，但 NuGet 还原时对包的目标框架筛选是按这个值精确匹配的，写错一个数字，还原出来的Npgsql.dll可能就是给 4.6 编译的版本。

2.2 Npgsql 版本怎么选：4.5 能用的上限在哪

Npgsql 从 4.x 开始逐步抬高框架门槛。根据官方发布记录，Npgsql 3.2.x 是最后一批明确支持 .NET Framework 4.5 的稳定版本线，4.0 之后最低要求提到了 4.6.1。所以在这台机器上，能选的范围基本锁定在 3.2.x 系列，常见可用的是 3.2.7 这个版本。

选版本时有个取舍要讲清楚：3.2.x 不支持 PostgreSQL 12 之后引入的一些新认证方式，比如scram-sha-256密码加密。如果目标数据库是 PostgreSQL 10 及以上并且服务端配置了password_encryption = scram-sha-256，用 3.2.x 连会直接报认证失败。常见做法是让 DBA 在服务端为这个应用单独建一个使用md5加密的账号，或者把pg_hba.conf里对应这条连接的认证方式改成md5。这不是驱动的问题，是版本能力边界，提前知道能省掉半天排查。

版本对照可以参照下面这张表，按目标数据库版本反推驱动版本：

如果项目实在绕不开 scram 认证，那就不是换驱动能解决的，得考虑升级目标框架到 4.6.1 以上再上 Npgsql 4.x，这是另一个工程量，不在这次安装范围内。

2.3 Mono.Security 的角色：它不是可选项

很多人以为Mono.Security.dll是 Npgsql 的可选依赖，只在启用 SSL 时才需要，这个理解是错的。Npgsql 3.2.x 在建立连接时，即使SSL Mode=Disable，内部的部分加密和哈希逻辑仍然会引用Mono.Security里的类型，尤其是处理密码认证和 SCRAM 相关代码路径时。缺了这个程序集，表现是运行时抛FileNotFoundException或TypeLoadException，堆栈指向 Npgsql 内部，看着完全不像缺依赖。

Mono.Security.dll的版本要和 Npgsql 3.2.7 配套，常见做法是直接从 Npgsql 3.2.7 的 NuGet 包依赖链里取，而不是从别处拷一个同名文件。NuGet 还原时如果项目是packages.config管理方式，Mono.Security会作为传递依赖被拉下来，版本号在packages.config里能看到。如果项目用的是PackageReference，那在.csproj里能看到隐式引用。两种方式都建议让 NuGet 自己解析，手工拷 DLL 是后面程序集冲突的主要来源。

提示：不要从其他项目目录直接复制Npgsql.dll和Mono.Security.dll到bin目录。这两个程序集有强名称，版本号对不上时 CLR 的绑定策略会拒绝加载，报错信息往往只给一个模糊的版本号，排查成本很高。

3. 安装落地：从 NuGet 还原到程序集绑定配置

3.1 用 NuGet 还原 Npgsql 3.2.7 及依赖

安装的第一步是把包拉对。Visual Studio 里操作和命令行操作结果一致，但我更倾向命令行，因为能看到还原日志里每个包的实际版本，出问题时好回溯。

在解决方案根目录打开命令行，执行：

# 安装 Npgsql 3.2.7 到指定项目，-Version 锁定版本避免拉到不兼容的新版 nuget install Npgsql -Version 3.2.7 -OutputDirectory packages # 查看还原结果，确认 Mono.Security 的版本被正确带下来 dir packages\Npgsql.3.2.7\lib dir packages\Mono.Security.*\lib

第一条命令的-Version 3.2.7是关键，不加这个参数，nuget install会拉最新稳定版，在 4.5 项目上直接不可用。-OutputDirectory packages指定包缓存目录，和项目里packages.config的路径保持一致，避免出现两份不同位置的同名包。第二条命令用来确认lib目录下有没有net45子目录，Npgsql 3.2.7 的包结构里lib\net45\Npgsql.dll就是给 4.5 用的，如果只看到net40或netstandard，说明包版本选错了。

还原完成后，在项目里添加对Npgsql.dll的引用，路径指向packages\Npgsql.3.2.7\lib\net45\Npgsql.dll。Mono.Security.dll一般会被自动加入引用，如果没有，手动从packages\Mono.Security.2.0.0\lib\net40\Mono.Security.dll添加。这里注意Mono.Security的lib目录是net40，不是net45，这是正常的，它在 4.5 上可以正常运行，不要因为目录名不对就去找别的版本。

3.2 配置 app.config 的程序集绑定重定向

装完包、加完引用，编译能过，但运行时仍可能报程序集版本不匹配。原因是项目里其他依赖可能间接引用了不同版本的Mono.Security，CLR 默认按强名称精确匹配，版本差一个修订号就加载失败。解决办法是在app.config（Web 项目是web.config）里加绑定重定向。

<configuration> <runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <!-- 把 Mono.Security 的所有旧版本请求统一重定向到 2.0.0.0 --> <dependentAssembly> <assemblyIdentity name="Mono.Security" publicKeyToken="0738eb9f132ed756" culture="neutral" /> <bindingRedirect oldVersion="0.0.0.0-2.0.0.0" newVersion="2.0.0.0" /> </dependentAssembly> <!-- Npgsql 同理，防止间接引用拉到其他版本 --> <dependentAssembly> <assemblyIdentity name="Npgsql" publicKeyToken="5d8b90d52f46fda7" culture="neutral" /> <bindingRedirect oldVersion="0.0.0.0-3.2.7.0" newVersion="3.2.7.0" /> </dependentAssembly> </assemblyBinding> </runtime> </configuration>

publicKeyToken必须和实际 DLL 一致，写错了重定向不生效且不报错，属于典型的静默失败。查 token 的方法是在命令行跑sn -T packages\Npgsql.3.2.7\lib\net45\Npgsql.dll，sn.exe在 Windows SDK 里。oldVersion的范围我一般写成0.0.0.0到目标版本，覆盖所有可能的旧引用，比只写具体版本号省事。newVersion填实际部署的版本，四位数字要完整，3.2.7要写成3.2.7.0。

注意：Web 项目的配置文件是web.config，节点位置在<configuration>下、<system.web>同级，不要塞进<system.web>里面，否则不生效。

3.3 连接字符串参数怎么配

驱动装好之后，连接字符串的配置直接决定能不能连上。Npgsql 3.2.7 的连接字符串关键字和后续版本有差异，几个容易写错的点单独说。

<connectionStrings> <!-- 基础连接：Host 支持 IP 或域名，Port 默认 5432 可省略 --> <add name="PgConn" connectionString="Host=192.168.1.20;Port=5432;Database=appdb;Username=appuser;Password=******;Timeout=15;CommandTimeout=30;Pooling=true;Minimum Pool Size=2;Maximum Pool Size=20;SSL Mode=Disable" providerName="Npgsql" /> </connectionStrings>

Timeout是建立连接的超时秒数，默认 15，内网环境够用，跨机房可以调到 30。CommandTimeout是单条命令执行超时，和连接超时是两回事，老项目里经常只配了前者忘了后者，导致慢查询把连接池占满。Pooling=true默认就是开的，显式写出来是为了让后来维护的人一眼看到。Minimum Pool Size设成 2 是为了避免应用空闲一段时间后首批请求全部走新建连接，冷启动时体感明显。SSL Mode=Disable在内网直连场景下是常见做法，如果数据库要求加密，改成Require并确认服务端证书配置，3.2.7 对证书校验比较严格，自签证书需要额外处理。

providerName写Npgsql是为了配合DbProviderFactories的注册，如果项目里用的是NpgsqlConnection直接 new，这个属性不影响运行，但写上更规范。如果项目通过ConfigurationManager.ConnectionStrings读取，name就是代码里引用的键名，改名字要同步改代码。

3.4 在代码里建立第一条连接并验证

配置写完，用一段最小代码验证驱动能加载、连接能建立、查询能返回。这段代码建议单独建一个控制台测试项目跑，不要直接塞进业务项目里，隔离变量。

using System; using System.Data; using Npgsql; class Program { static void Main() { // 连接字符串从配置文件读取，避免硬编码 string connStr = System.Configuration.ConfigurationManager .ConnectionStrings["PgConn"].ConnectionString; using (var conn = new NpgsqlConnection(connStr)) { try { conn.Open(); // 触发实际连接，程序集加载问题会在这里暴露 using (var cmd = new NpgsqlCommand("SELECT version()", conn)) { Console.WriteLine(cmd.ExecuteScalar().ToString()); } } catch (Exception ex) { // 打印完整异常链，内层异常往往才是根因 Console.WriteLine(ex.ToString()); } } } }

conn.Open()这一行是整段代码的关键，程序集加载、认证、网络连通性三类问题都会在这一步集中暴露。ex.ToString()而不是ex.Message，是因为FileLoadException这类问题的根因经常藏在InnerException里，只看 Message 会漏掉版本号信息。SELECT version()返回服务端版本字符串，能同时验证查询通道正常。跑通这段，说明驱动安装和基础配置这一层已经过了，剩下的就是业务代码适配。

4. 避坑与排查：这套组合最常见的五类翻车

4.1 现象：编译通过但运行时报找不到 Mono.Security

原因通常是bin目录里没有Mono.Security.dll，或者有但版本和引用清单不一致。NuGet 还原时如果项目是packages.config方式，有时候Mono.Security被标记为developmentDependency或者被手动从引用里移除过，编译期不报错是因为编译器只检查直接引用的类型，运行期 Npgsql 内部反射加载时才失败。

解决分两步：先确认bin目录下文件存在且版本正确，用sn -T查 token 和版本；再检查.csproj里Mono.Security的<Reference>节点有没有SpecificVersion设成true且版本号写错。我一般把SpecificVersion设为false，配合绑定重定向，让 CLR 按重定向规则解析，比锁死版本灵活。

4.2 现象：连接报 28P01 认证失败，密码明明是对的

在 PostgreSQL 10 及以上版本上，服务端默认password_encryption可能是scram-sha-256，而 Npgsql 3.2.7 只支持md5。客户端发起的认证请求服务端不认，返回密码错误，但实际密码没错。

解决方式是让 DBA 确认目标账号的密码加密方式：SELECT rolname, rolpassword FROM pg_authid WHERE rolname='appuser';，看前缀是md5还是SCRAM-SHA-256。如果是后者，用ALTER USER appuser WITH PASSWORD '...'在password_encryption = md5的会话里重设一次，或者直接改pg_hba.conf对应行的认证方法为md5后 reload。改完不需要重启数据库，pg_ctl reload即可。

4.3 现象：偶发连接超时，重启应用就好

连接池配置不当的典型表现。Maximum Pool Size设得过大而数据库max_connections有限，高峰期连接池不断新建连接，超过服务端上限后新连接被拒，表现为超时。另一种情况是CommandTimeout没配，慢查询长期占用连接不释放，池子被耗尽。

排查时先看服务端pg_stat_activity里当前连接数和状态分布，再看应用侧连接池的Count和Available指标。解决上把Maximum Pool Size压到服务端max_connections的 60% 左右，给运维和其他应用留余量；CommandTimeout按业务最长查询时间设，超时的命令主动断开而不是无限等。

4.4 现象：绑定重定向写了但不生效

最常见的原因是publicKeyToken写错，或者oldVersion范围没覆盖到实际请求的版本。重定向不生效时 CLR 不会报配置错误，只会继续按原版本加载然后失败，日志里看不出配置问题。

排查方法是在应用启动时打印AppDomain.CurrentDomain.GetAssemblies()里已加载的Npgsql和Mono.Security版本，和配置文件里的newVersion对比。另一个容易忽略的点是配置文件放错位置：控制台项目的配置文件必须叫App.config且生成到输出目录后改名项目名.exe.config，Web 项目是站点根目录的web.config，放错位置等于没配。

4.5 现象：开发机正常，部署到服务器就报 FileLoadException

开发机和服务器上安装的 .NET Framework 补丁级别不同，或者服务器GAC里存在同名不同版本的程序集，CLR 的加载顺序和开发机不一致。还有一种情况是服务器上部署目录里残留了旧版本的Npgsql.dll，新文件没覆盖成功。

解决上先对比两边Release注册表值，确保补丁级别一致；再检查部署目录bin下文件的时间戳和版本号，用sn -T逐个确认；最后看GAC里有没有同名程序集，gacutil /l Npgsql能列出来。部署脚本里我一般加一步校验bin目录下关键 DLL 的版本，不匹配就中止发布，比上线后才发现强。

5. 装完怎么验证：三层检查让连接真正跑通

装完不等于跑通，我习惯用三层检查收尾，从程序集加载到连接建立再到业务查询，每层都有明确的通过标准，任何一层不过都不算完成。

第一层是程序集层，确认Npgsql.dll和Mono.Security.dll被正确加载且版本符合预期。在测试程序里加一段启动日志：

// 在应用启动入口打印关键程序集版本，作为部署后的自检 var asm = AppDomain.CurrentDomain.GetAssemblies() .FirstOrDefault(a => a.GetName().Name == "Npgsql"); Console.WriteLine(asm != null ? $"Npgsql loaded: {asm.GetName().Version}" : "Npgsql NOT loaded");

通过标准是输出3.2.7.0，且Mono.Security同样能查到2.0.0.0。如果输出NOT loaded，说明引用没生效或绑定重定向把加载推迟了，回到第 3 章检查引用和配置。

第二层是连接层，用第 3.4 节的测试代码跑一次conn.Open()，通过标准是无异常且SELECT version()返回服务端版本字符串。这一层能过，说明网络、认证、驱动三者都通了。建议把这段测试代码保留在项目里作为一个隐藏的诊断入口，线上出问题时能快速区分是驱动问题还是业务问题。

第三层是业务层，用实际业务里最复杂的那条查询跑一次，确认参数类型映射正确。Npgsql 3.2.7 对jsonb、uuid、timestamp with time zone这些类型的映射和后续版本有差异，比如jsonb在 3.2.x 里需要显式转string处理，直接当object取会得到NpgsqlTypes的内部类型。通过标准是查询结果和用psql命令行查出来的完全一致，字段类型转换没有精度丢失。

三层都过之后，还有一件事值得做：把这次用到的包版本、绑定重定向配置、连接字符串模板整理成一个部署检查清单，放进项目的docs目录。老项目的维护周期长，人员流动大，下次换机器部署时照着清单走，比重新踩一遍坑省事得多。

从那以后我每次给老框架项目配数据库驱动，都强制先跑一遍这三层检查再交付，尤其是程序集版本这一层，宁可多花十分钟确认，也不想半夜被叫起来看FileLoadException。这套 Npgsql 加 Mono.Security 的组合在 .NET Framework 4.5 上虽然版本受限，但把版本锁死、绑定重定向配好、连接参数调对，跑起来是稳的。希望帮到你。

本文还有配套的精品资源，点击获取