EFCore 3.1 连接达梦8最小工程：适配包、连接串与避坑指南

简介EF Core 3.1对接达梦8数据库的实战示例项目面向需要在国产化数据库环境下使用微软ORM框架的.NET开发者。压缩包内以ConsoleApp1控制台应用程序为入口包含完整的DbContext配置、实体类定义以及增删改查操作代码项目结构直观便于快速了解达梦8数据库与EF Core的整合方式。包内共83个文件以dll与exe运行文件、cs源代码、json配置及cache缓存文件为主整体仅1.79MB轻量易下载其中7个cs文件清晰呈现核心代码逻辑4个exe可直接运行观察效果。已有179人学习下载适合正在将.NET应用迁移到达梦数据库或需要配置EF Core达梦提供程序如DAMENG.EntityFrameworkCore的开发者参考。解压后即可对照源码学习连接字符串写法、OnConfiguring配置方法及SaveChanges持久化流程节省自行摸索的时间。1. EFCore 3.1 连达梦 8 的示例包国产化选型期最缺的那份最小工程接到信创改造任务的老 .NET 工程师大概都经历过这个阶段系统跑在 .NET Core 3.1 上EF Core 3.1 用了两年突然通知要把底层数据库从 SQL Server 换成达梦 8。官方文档几百页社区案例稀缺GitHub 上翻半天也找不到一份能直接跑起来的样例。这个压缩包就是干这个用的——一个名为 ConsoleApp1 的最小控制台工程把 EF Core 3.1 通过达梦适配器连上达梦 8 数据库的完整链路做成了可复现的例子。它不解决业务问题解决的是选型评估期最痛的那个问题连接串怎么写、包该装哪个、增删改查能不能跑通。适合准备做达梦适配评估、或者刚接到迁移任务想先花半小时验证可行性的工程师。2. 先看懂这条连接链路达梦 8 的 EF Core 提供者与项目结构2.1 EF Core 3.1 为什么需要单独的达梦适配包EF Core 本身是一个 ORM 框架它不直接认识达梦 8也不认识 Oracle、MySQL。EF Core 与具体数据库之间的桥梁叫“数据库提供者”Database Provider它在内部实现了IEntityTypeMappingSource、IQueryTranslationPreprocessor等抽象接口把 LINQ 表达式翻译成对应数据库的 SQL 方言。SQL Server 能用UseSqlServerMySQL 能用UseMySqlOracle 能用UseOracle达梦要连就得有对应的UseDAMENG之类的扩展方法。这个扩展方法不是微软官方提供的。达梦官方提供的适配包里封装了自己的 ADO.NET 驱动底层的连接和命令走的是达梦原生驱动EF Core 只负责把表达式树变成文本 SQL。EF Core 3.1 是 .NET Core 3.1 时代的版本它的 API 面和 EF Core 5.0、6.0 差别不小所以适配包必须对应 3.1 的版本不能用更高版本适配包强行落到 3.1 项目里。这一点在后续踩坑章节会单独展开。2.2 解压后先看这三个文件这个压缩包解压后是一个完整控制台解决方案包含ConsoleApp1.sln解决方案文件和ConsoleApp1项目目录。obj和bin是构建产物project.assets.json是 NuGet 还原生成的依赖清单这些都不用手动碰。真正要读的是三个文件。第一个是ConsoleApp1.csproj。这个文件里定义了目标框架和 NuGet 引用。示例用的是 .NET Core 3.1TargetFramework对应netcoreapp3.1。PackageReference里应该能看到达梦适配包和Microsoft.EntityFrameworkCore的版本号。核对这两个版本是否匹配是跑通例子的第一道关。第二个是Program.cs。这是控制台入口通常的套路是创建DbContext实例 → 执行插入或查询 → 打印结果。这个文件决定例子的演示路径——是只测连接还是做了完整增删改查。第三个是Class1.cs。名字起得很随意但在这个例子场景里它一般放实体类和DbContext派生类。看到它你就能确认实体属性与达梦表字段的映射方式。文件类型该不该改备注ConsoleApp1.csproj通常不用改核对包版本即可Program.cs可能要改连接串主逻辑入口Class1.cs可能要改实体/上下文表名、字段映射obj/bin 目录不用管构建还原产物ConsoleApp1.sln不用改直接双击或用 dotnet 命令加载2.3 为什么示例偏要用控制台项目见过不少人质疑生产环境是 Web 项目拿控制台样例有什么用恰恰是这个“最小形态”最有价值。控制台项目没有 IIS、没有 Kestrel、没有依赖注入容器那一整套运行链路最短问题最容易暴露。连接失败时报错堆栈里只有 ADO.NET 驱动和 EF Core排除了框架层的干扰。我一般会先跑通控制台例子确认连接串、驱动、SQL 翻译三个环节没问题再往 Web 项目里迁。这个顺序能省下大量排查时间——否则 Web 项目里一旦出问题你没法判断是数据库连不上还是依赖注入配置错了。3. 把 ConsoleApp1 跑起来还原依赖、改连接串、跑增删改查3.1 还原 NuGet 依赖拿到压缩包的第一步是还原 NuGet 包。解压后进入ConsoleApp1目录执行dotnet restore如果本机装了 Visual Studio也可以在 IDE 里直接打开ConsoleApp1.sln让 VS 自动还原。dotnet restore会读取ConsoleApp1.csproj里的PackageReference把Microsoft.EntityFrameworkCore和达梦适配包下载到本地 NuGet 缓存并生成project.assets.json。对于这个例子本身dotnet restore的目的是确认依赖能拉下来。如果公司内网有 NuGet 私有源需要先配置好源地址如果提示“找不到包”多半是适配包的包名或版本不对这个在避坑章节会详说。还原成功后直接dotnet run就能看例子能不能跑但通常连接串还没改成你的达梦环境所以先改连接串。3.2 连接串怎么改达梦 8 的连接串写法跟 SQL Server 差异很大。SQL Server 常用的Serverxxx;Databasexxx;User Idxxx;Passwordxxx在这里不完全适用。达梦适配器通常认下面的写法optionsBuilder.UseDAMENG( Server127.0.0.1;Port5236;UserIdSYSDBA;PasswordSYSDBA;SchemaTEST );这个连接串里最关键的是Port。达梦 8 默认端口是 5236不是 SQL Server 的 1433也不是 MySQL 的 3306。UserId默认可以用达梦安装时自带的SYSDBA账号Password是安装时设置的密码如果没改过很多环境是SYSDBA但这要跟安装达梦的人确认不要瞎猜。Schema参数对应达梦里的“模式”。达梦的一个特点是一个模式对应一个用户默认情况下访问某个用户下的表Schema 要写那个用户名。如果省略这个参数可能会在查询时报“表或视图不存在”这个坑后面专门讲。3.3 定义实体与 DbContext示例里Class1.cs大概长这样——定义一张测试表的实体再写一个DbContext派生类public class TestUser { public int Id { get; set; } public string Name { get; set; } public int Age { get; set; } } public class TestDbContext : DbContext { public DbSetTestUser TestUsers { get; set; } protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { optionsBuilder.UseDAMENG( Server127.0.0.1;Port5236;UserIdSYSDBA;PasswordSYSDBA;SchemaTEST ); } }实体类的属性名建议跟达梦表的字段名保持一致或者用[Column(字段名)]标注。如果达梦表里字段是大写C# 属性用 PascalCase 没问题因为达梦和 EF Core 会在 SQL 翻译时自动处理大小写但如果你有[Table(表名)]特性没写对就会撞上“表或视图不存在”的报错。OnConfiguring是 EF Core 的经典配置入口。它适合示例这种不用依赖注入的场景直接写死连接串。真实项目里建议改成从配置文件读但示例坚持用这种方式能少一层配置干扰。3.4 增删改查演示Program.cs里的主逻辑通常会演示插入和查询两件事using (var context new TestDbContext()) { var user new TestUser { Name 张三, Age 30 }; context.TestUsers.Add(user); context.SaveChanges(); var list context.TestUsers .Where(u u.Age 18) .ToList(); foreach (var item in list) { Console.WriteLine(${item.Id} - {item.Name} - {item.Age}); } }这段代码覆盖了 EF Core 做增删改查的最小闭环。Add方法把实体标记为Added状态SaveChanges在后台生成 INSERT 语句并交给达梦执行。查询走的 LINQ 表达式Where(u u.Age 18)会被翻译成带 WHERE 子句的 SQL。运行这段代码时控制台会输出查询结果这说明整条链路已经通了连接串配置正确、适配包版本匹配、SQL 方言翻译没有致命错误。如果在这里就翻车问题基本集中在连接串和包版本上往下走会撞到更隐蔽的坑。4. 参数边界与行为差异连接串字段、并发与 SQL 翻译4.1 连接串字段逐项拆解达梦适配器的连接串字段看着跟 SQL Server 有点像但含义和可选项完全不同。用一张表把常见字段说清楚参数示例值作用要不要必填Server127.0.0.1达梦服务器 IP必填Port5236达梦监听端口必填UserIdSYSDBA登录用户名必填Password对应密码登录密码必填SchemaTEST默认模式对应达梦的一个用户建议填Poolingtrue/false是否启用连接池可选Connection Timeout30连接超时秒数可选CharsetUTF-8字符集解决中文乱码按需Schema参数值得多说一句。达梦跟 SQL Server 最大的不同是SQL Server 里数据库和用户是独立的库里有多个 schema达梦里默认一个用户对应一个 schemaSYSDBA登录后默认访问SYSDBA模式如果你想访问TEST用户建的表要么在 SQL 里写TEST.表名前缀要么在连接串里指定SchemaTEST。4.2 和 SQL Server 三个最不同的体验先说说大小写。SQL Server 默认不区分大小写表名写成Users或users都能查到。达梦默认创建的对象名是大写存储EF Core 翻译 SQL 时如果不加引号达梦会把标识符统一转成大写再匹配。所以 C# 实体名用TestUser没问题翻译出来是TESTUSER能和库里的表对应上。但如果你的表是建表时用小写加双引号创建的那 EF Core 生成的未加引号 SQL 就匹配不上了。再说分页。EF Core 对Skip/Take的翻译SQL Server 用的是OFFSET ... FETCH达梦 8 不同版本对分页 SQL 的支持方式不同。较新的版本支持OFFSET子句老版本或有限制版本可能要走ROWNUM方式。适配包版本较旧时Skip/Take可能被翻译成先取全表再内存分页——数据量小没感觉数据量大就等着内存爆炸吧。第三个是布尔处理。SQL Server 有bit类型C# 的bool属性映射到 bit查询时直接WHERE IsActive 1。达梦没有 bit 类型通常用 NUMBER(1) 或 TINYINT 代替适配器在赋值和比较时可能需要特殊处理。如果实体里定义了bool属性达梦侧对应字段就得保证是整数 0/1否则写入会报类型转换错误。4.3 并发与事务SaveChanges 的批量性能数据库并发这块达梦支持标准的BEGIN TRAN事务和普通行锁这块不像连接串那样有那么多差异。真正要警惕的是 EF Core 的逐条写入模式SaveChanges默认一条一条地 INSERT循环 10000 条就是 10000 次往返。在达梦 8 上调大批量数据导入时这个性能差距会特别明显。常见做法是缩小事务粒度分批调用SaveChanges比如每 500 条提交一次。如果导入量级更大就别用 EF Core 了直接拼INSERT INTO ... VALUES (...), (...)批量语句或者用达梦自带的数据装载工具EF Core 只负责业务查询那条链路。事务和并发锁这块EF Core 的Database.BeginTransaction在达梦适配器上是可用的正常提交回滚都能工作。但如果你的应用是长事务里套大量写入小心“数据库死锁”这个经典问题——多个事务交叉更新同一批行达梦会按顺序锁资源长时间不释放就可能触发死锁检测。遇到这种场景把事务范围缩小让锁持有时间变短比调锁超时参数更有效。5. 避坑EFCore 3.1 连达梦 8 的五个翻车现场5.1 现象照抄 SQL Server 连接串报“不支持关键字”有人直接把Serverxxx;Databasexxx;User Idxxx;Passwordxxx换成UseDAMENG运行时报 “Keyword not supported” 或“连接字符串中的 Data 参数不受支持”。原因很简单达梦适配器的连接串解析器不认Database、User Id这些 SQL Server 风格的关键字。解决改用达梦适配器自己的关键字。注意UserId中间没有空格不是User IdDatabase在达梦里对应的是Schema。改完再跑这个报错就消失了。5.2 现象装了包但找不到 UseDAMENG 扩展方法代码里明明写好了optionsBuilder.UseDAMENG(...)编译却说上下文没有这个方法。原因通常是装了错误的包——有人装的是达梦的 ADO.NET 驱动包比如只有DmProvider那个包只提供底层连接不提供 EF Core 的UseDAMENG扩展方法也有人装了高版本适配包但项目是 .NET Core 3.1版本错位导致方法签名不匹配。解决确认ConsoleApp1.csproj里的PackageReference是达梦官方 EF Core 适配包并且版本对应 EF Core 3.1。还原后到 NuGet 缓存里查一下包的实际版本如果目标框架不是 netcoreapp3.1把它卸了重装正确版本。5.3 现象客户端能看到表EF Core 查询报“表或视图不存在”用达梦管理工具连接同一个库能看到TEST_USER表查数据也没问题但程序跑context.TestUsers.ToList()就报无效的表名。原因就是连接串里没配SchemaEF Core 默认在当前用户模式里找表而你要查的表在另一个 schema 下。解决连接串里补上SchemaTEST或者实体上打[Table(TEST_USER)]配合[Schema(TEST)]。两个方案选一个优先改连接串因为只动一处就能全局生效。5.4 现象Skip/Take 分页翻车数据被全量查出列表页用Skip(20).Take(10)做分页肉眼观察还没什么问题后台日志显示 EF Core 把整张表都查出来了然后在内存里做分页。数据量在十几万行时这一条查询能把应用内存打满。原因是适配包版本较旧没有把Skip/Take翻译成达梦的分页方言而是退化成全表扫描加内存操作。解决升级达梦 EF Core 适配包到一个较新版本。升级后观察生成的 SQL 是否出现了LIMIT或ROWNUM相关子句。如果适配包迟迟不更新退路是写原生 SQL 查询FromSqlRaw可以绕过 LINQ 翻译直接执行达梦方言分页和性能问题一次解决。5.5 现象写入中文正常查询出来是乱码插入数据库的中文在管理工具里看是乱的或者查出来显示成问号。这是因为达梦实例的初始化字符集与客户端编码不一致。达梦 8 安装时可以选字符集常见的有 UTF-8 和 GBK客户端连接串里如果不显式指定可能走了默认字符集。解决连接串加CharsetUTF-8如果达梦实例是 GBK 就写 GBK保持两端一致。如果已经写入了大量乱码数据先改连接串再重新插入测试行——之前写坏的旧数据只能靠更新语句或重导修复。检查字符集要两头看达梦实例初始化参数和连接串里的 Charset 配置。6. 确认它真的连通了两个能直接抄的验证技巧6.1 打开 EF Core 日志看翻译出来的 SQL连接串对了、包对了但增删改查出来的结果对不对不能只靠眼睛看。我习惯在DbContext配置里直接打开日志让 EF Core 把每次生成的 SQL 打到控制台protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { optionsBuilder .UseDAMENG(Server127.0.0.1;Port5236;UserIdSYSDBA;PasswordSYSDBA;SchemaTEST) .EnableSensitiveDataLogging() .LogTo(Console.WriteLine); }LogTo(Console.WriteLine)是 EF Core 3.1 里注册日志输出的方式它把执行的 SQL、参数值、执行耗时都打到控制台。EnableSensitiveDataLogging会把参数值明文打出来方便核对写入的参数是不是预期的值。看日志重点看三处SQL 里表名有没有带前缀、WHERE 条件是否合理、有没有出现全表扫描的分页 SQL。6.2 用一条原生 SQL 做连通性冒烟连接问题最容易和业务代码搅在一起所以我每次换数据库环境都会先跑一条原生 SQLusing (var context new TestDbContext()) { var result context.Database .ExecuteSqlRaw(SELECT 1); Console.WriteLine(Connectivity OK); }ExecuteSqlRaw绕过 EF Core 的 LINQ 翻译直接把 SQL 文本交给达梦执行。它能通说明底层 ADO.NET 驱动、连接串、网络三件事没问题它不通问题还在连接链路里别急着查业务代码。注意ExecuteSqlRaw返回的是受影响行数对 SELECT 语句来说通常返回 -1这正常别当成异常。从那以后我每次接达梦或任何国产数据库的迁移任务都强制自己先走一遍这个流程还原示例项目、改连接串、开日志、跑原生 SQL 冒烟然后再把业务代码搬过来。这套流程帮我避开了无数个“连接看着通了但 SQL 翻译有毛病”的隐蔽问题。希望这份例子包和里面的踩坑记录能帮你把达梦适配的第一公里走顺。本文还有配套的精品资源点击获取