做C#上位机这几年数据库操作这一块我换过不少写法。早年用ADO.NETSQL写了一大堆不说碰到SqlServer、SQLite、MySQL来回切换的时候光改连接字符串和方言语法就能折腾一下午后来试过EF Core又重又慢工控机上跑兼容性也一般。直到接触SqlSugar才算是把数据库层的代码稳定下来了。这篇文章不打算讲百科式的API罗列就围绕我在实际项目里怎么用它、踩了哪些坑、哪些功能真正帮了大忙写点能直接拿去用的东西。1. 为什么在多种C# ORM里我最终选了SqlSugar1.1 从ADO.NET硬写SQL到ORM不是偷懒是为了少犯错最早我也是纯ADO.NET派SqlConnection打开、SqlCommand拼SQL、DataTable接结果一条流水线写得滚瓜烂熟。但真正到了项目后期问题全冒出来了字段改动后手写SQL很容易漏改。表结构从A改成B的时候代码里的SELECT *和INSERT INTO改不全运行起来才报错测试成本特别高。数据量上来之后DataTable在内存里的开销很大。上位机软件本来就要长期跑动不动几十万行数据塞内存GC压力一上来界面卡顿跟着就来了。数据库切换几乎是“伤筋动骨”。厂里原本用SqlServer测试机上想换SQLiteSQL语句里带了一堆GETDATE()、WITH(NOLOCK)改起来那叫一个痛苦。ORM解决的不只是“少写代码”这么简单它强制你把“数据结构”和“数据访问逻辑”分开。实体类定义好之后字段变更在编译期就能发现至少不会出现“改库没改代码”的低级事故。1.2 EF Core和Dapper为什么不那么顺手我并不是没试过EF Core。装包、建DbContext、写迁移一套流程下来确实规范但工控场景里有个很现实的问题EF Core太重了。启动时要反射扫描、初始化模型缓存工控机配置普遍不上台面加载速度肉眼可见地慢。更重要的是EF Core的复杂查询一旦写不好生成的SQL绕来绕去调试起来头大。对上位机这种“要稳定、要快、要轻量”的场景来说它更偏向大型Web系统。Dapper是个好库轻量而且性能高但它的定位是“micro ORM”——SQL还是得你自己写只是帮你执行和映射。如果项目里有一堆复杂的联表查询、分页、动态条件拼接Dapper给不了太多帮助等于还是半只脚踩在ADO.NET里。SqlSugar恰好卡在中间比Dapper封装全比EF Core轻量文档全中文社区活跃度高。尤其在国内工控、桌面端项目里SqlSugar的出镜率相当高遇到问题一搜就有解决方案。1.3 工控场景下的选型标准我做上位机项目时对数据库层有非常具体的诉求这也是我最终选择SqlSugar的直接原因诉求说明SqlSugar的实际表现支持多数据库交付到现场后客户可能用SqlServer、MySQL、Oracle甚至SQLite内置多种DbType连接配置切换基本只改一行长期稳定运行软件经常7x24小时挂机连接管理不能出岔子IsAutoCloseConnection机制和连接池策略都算成熟高频写入优化采集数据频繁单条Insert撑不住自带BulkCopy、BulkMerge批量写入处理百万级写入有余力快速开发迭代上位机需求变化多不能把时间耗在SQL上实体映射加Lambda查询业务代码量下降一个量级可维护性后期接手的同事能看懂查询表达式即查即得不需要翻一大段SQL字符串2. 五分钟搭好基础连接配置与实体映射里的坑2.1 最小可用的SqlSugarClient不管你是.NET Framework还是.NET Core先用NuGet把包装上。新版直接用SqlSugarCore就行dotnet add package SqlSugarCore然后写一个最基础的工具类public class DbContext { public static SqlSugarClient GetInstance() { SqlSugarClient db new SqlSugarClient(new ConnectionConfig() { DbType DbType.SqlServer, ConnectionString Serverlocalhost;DatabaseDeviceDB;User Idsa;Password123456;, IsAutoCloseConnection true, InitKeyType InitKeyType.Attribute }); return db; } }ConnectionConfig里有几个参数很多人第一次用的时候看都不看就往下写后面出了问题才回头补功课我逐个说下DbType数据库类型把DbType.SqlServer换成DbType.MySql连接串一换代码基本不用动。这是SqlSugar最实在的一个优势。IsAutoCloseConnection默认是false建议开发阶段直接设为true。它的作用是每次执行完SQL后自动关闭连接避免你忘了Close()导致连接池耗尽。后面讲多线程高频读写的时候我会专门说明这个参数在大批量事务场景下要怎么配合。InitKeyType.Attribute告诉框架以实体类上的特性为主键、自增列的判断依据。还有一种InitKeyType.SystemTable是读取数据库表结构来判断主键不过那要额外查系统表没必要。2.2 实体类里那些不起眼的特性实体映射是ORM的基石SqlSugar用SugarTable和SugarColumn两个特性来做映射。我见过很多新手把数据库字段直接声明成public属性就完事结果遇到字段名对不上、主键不自增、不想入库的字段被写进去等问题非常折腾。一个常见做法是这样[SugarTable(device_info)] public class DeviceInfo { [SugarColumn(IsPrimaryKey true, IsIdentity true)] public int Id { get; set; } [SugarColumn(ColumnName device_name)] public string DeviceName { get; set; } [SugarColumn(ColumnName create_time)] public DateTime CreateTime { get; set; } [SugarColumn(IsIgnore true)] public string TempData { get; set; } }这里值得注意的三个点IsPrimaryKey和IsIdentity必须配对设置否则做更新操作时SqlSugar找不到主键条件容易生成全表更新SQL。ColumnName用来把数据库里的下划线命名映射成C#的驼峰命名。很多老系统的表字段是DEVICE_NAME这种风格实体里写成DeviceName通过ColumnName对上。IsIgnore标记的字段不会参与数据库读写。比如你实体里存了一个只是界面展示用的临时字段不标记的话SqlSugar会默认把它当成一个数据库列轻则报列不存在重则自动建表时多建一列。2.3 CodeFirst同步表结构的正确姿势SqlSugar支持从实体类自动建表db.CodeFirst.InitTables(typeof(DeviceInfo));这个功能做原型验证很好用部署到现场后新增一张配置表直接跑一行代码就把表建出来了。但有个大坑InitTables只会“加”字段不会“删”字段也不会主动帮你“改”字段类型。你改了实体的属性类型同步表结构时数据库那边没反应最容易出问题的是把int改成long、string加长度数据库里存的还是旧定义。所以在正式环境里我一般只在开发机或者初始化阶段跑一次表结构同步线上变更走脚本绝不能依赖CodeFirst。3. 查询的日常与进阶从WhereIF到联表分页3.1 表达式查询背后的门道SqlSugar最常用的入口是QueryableT()。比如查所有状态正常的设备var list db.QueryableDeviceInfo() .Where(x x.Status 1) .ToList();这段代码看起来就是普通Lambda实际上SqlSugar内部把它拆成了表达式树再翻译成对应的SQL方言。这也是为什么同样的代码可以跑在SqlServer和MySQL上——你不是在写SQL而是在用C#表达式描述查询逻辑。在写表达式时尽量别用ToString()、DateTime.Parse这类C#方法表达式树翻译器未必认得最好直接用可翻译的写法比如x.CreateTime DateTime.Now.AddDays(-1)是可以的x.CreateTime.ToString()就不一定翻译得过来。3.2 动态拼条件上位机参数查询面板的利器上位机界面里最常见的场景是界面上有一堆筛选条件用户爱填哪个填哪个不填的默认不过滤。如果用字符串拼SQL先判断再拼接很容易拼出语法错误甚至引来注入问题。SqlSugar提供了WhereIF写法非常丝滑var query db.QueryableDeviceInfo() .WhereIF(!string.IsNullOrEmpty(deviceName), x x.DeviceName.Contains(deviceName)) .WhereIF(status.HasValue, x x.Status status.Value) .WhereIF(startTime.HasValue, x x.CreateTime startTime.Value) .WhereIF(endTime.HasValue, x x.CreateTime endTime.Value);这段代码的语义是条件成立才追加过滤。我实际用下来最大的感受是查询面板再怎么变查询方法改动量都很小而且不会出现SQL关键字漏掉导致的语法错误。WhereIF的第一个参数是bool只要你能写出这个bool过滤条件就能随意组合。3.3 分页与排序不用再手写ROW_NUMBER()老的SQL写法里分页基本就是ROW_NUMBER()或者OFFSET FETCHSqlServer和MySQL语法还不一样。SqlSugar把分页封装成了ToPageListAsync配合排序表达式直接一条链子写下来var page await db.QueryableDeviceInfo() .Where(x x.Status 1) .OrderBy(x x.CreateTime, OrderByType.Descending) .ToPageListAsync(pageIndex, pageSize); int totalCount page.TotalCount; var list page.Items;返回值是PageModelTTotalCount和Items都帮你装好了不用再单独写一条SELECT COUNT(*)。这里要提一个细节分页查询一定要带OrderBy。没有排序的分页是“不稳定分页”——用户在翻页过程中数据顺序可能变化导致某条记录重复出现或者丢失。这个坑我踩过一次后来养成了条件反射只要分页必然先排序。3.4 联表查询LeftJoin设备主表和配置表设备信息一般拆成主表和配置表查询的时候又要把它们合到一起。SqlSugar的联表查询写起来比较接近SQL直觉var list await db.QueryableDeviceInfo() .LeftJoinDeviceConfig((d, c) d.Id c.DeviceId) .Where(d d.Status 1) .Select((d, c) new DeviceInfoView { DeviceName d.DeviceName, ConfigContent c.ConfigContent, UpdateTime c.UpdateTime }) .ToListAsync();LeftJoinDeviceConfig后面的Lambda就是联表条件Select里指定要返回的字段。这里要注意的是Select别用select *的习惯只取实际需要的列否则联表结果会把两张表的全部字段都查出来数据量大时性能差异非常明显。3.5 子查询与导航查询SqlFunc的巧妙用法有时候一个子查询就能解决的事没必要join。比如要查“有有效配置的设备”我用SqlFunc.Subqueryablevar list await db.QueryableDeviceInfo() .Where(d SqlFunc.SubqueryableDeviceConfig() .Where(c c.DeviceId d.Id c.IsValid 1) .Any()) .ToListAsync();这种写法生成的SQL就是EXISTS (SELECT 1 FROM ...)可读性和执行效率都不错。SqlSugar还提供了导航查询Navi可以直接通过实体属性导航关联数据不过我个人倾向在查询层用Select显式指定因为导航查询默认会加载全部关联字段而且延迟加载行为容易让人迷惑。上位机项目里“查询逻辑明确”比“代码写得短”更重要。4. 存储过程与大数据写入两种真正的“重武器”4.1 SqlSugar调用存储过程这一步很多老项目都在用Web项目里存储过程已经不多见了但工业现场的老系统完全不愁这个——厂里的MES、SCADA、DCS系统后台一堆业务逻辑都封装在存储过程里。上位机作为前端经常需要直接调这些存储过程拿数据。这时候SqlSugar的Ado直接用起来var dt db.Ado.UseStoredProcedure().GetDataTable(sp_GetDeviceHistory, new SugarParameter(deviceId, deviceId), new SugarParameter(startTime, startTime), new SugarParameter(endTime, endTime));几个细节UseStoredProcedure()是必须的否则SqlSugar会把存储过程名当成普通SQL去执行直接语法报错。参数类型用SugarParameter包装而不是SqlParameter因为要适配多种数据库。如果存储过程有返回值或output参数用SugarParameter的Direction属性设置比如new SugarParameter(outCount, 0) { Direction ParameterDirection.Output }执行完再读Value。还有一点是调用存储过程时如果涉及事务一定要把Ado和事务绑定在一起后面讲多线程那部分会详细说。4.2 批量写入一万条数据别一条一条Insert上位机采集的数据经常是满屏好几万条记录往库里灌。如果还在循环里一条条Insertable不仅慢还容易把数据库连接搞得压力很大。SqlSugar提供了原生的批量插入ListDeviceRecord records GetRecordsFromBuffer(); var result db.Insertable(records).ExecuteCommandBulkCopy();ExecuteCommandBulkCopy对应的就是SqlServer的SqlBulkCopy接口底层走的是大数据批量通道。我以前用SqlBulkCopy得手动建DataTable、逐列映射现在直接传实体集合就完事。实测下来在普通工控机上写入一万条记录从原来一条条Insert的十几秒降到了几秒以内这个差距在现场非常明显。需要留意的是ExecuteCommandBulkCopy不会帮你自动维护主键如果表有自增主键插入后你可能拿不到新生成的ID。要回填主键得用Insertable(list).ExecuteReturnIdentity()。4.3 BulkMerge更新与插入的天然合并现场还有一种很常见的场景采集数据带状态记录不存在就插入存在就更新。用SqlSugar的BulkMerge来做一条链子解决db.Storageable(records) .WhereColumns(x x.Id) // 指定判断重复的列 .ToStorage();这里解释一下Storageable的机制它把实体集合先做一次“对比分析”根据主键或指定列判断每条记录是“该插入”还是“该更新”然后可以分别获取insertList和updateList再做对应操作。这个方法在批处理现场数据时特别好用不用自己先查一次再去分别Insert和Update。用Storageable还有一个额外好处它可以返回“哪些数据有变化”方便做增量日志。具体用法可以看官方文档我只说一句——这类批处理接口才真正体现了ORM不是为了写SQL方便而是为了让你少写几十行业务逻辑。5. 多线程与高频读写的稳定性实践5.1 连接管理IsAutoCloseConnection开还是关在工控上位机里界面线程和采集线程往往是同时存在的。采集线程在后台不断写库UI线程时不时要读数据库刷新画面这就对连接的管理能力提出了要求。IsAutoCloseConnection false时连接会长时间占用配合连接池在压力大时容易打满IsAutoCloseConnection true时每次操作短连接、自动释放对上位机这种“频繁但不重”的读写模式更合适。但开头的“坑”也很明确如果在一个事务里框架本来依赖同一个连接你把IsAutoCloseConnection设为true事务可能在中途就断掉。所以我的做法是常规查询和单条操作保持true进入事务时显式BeginTran让事务期间连接一直保持打开结束后再CommitTran。5.2 SqlSugarClient不是线程安全的改用SqlSugarScope这是一个非常容易炸雷的地方。SqlSugarClient实例本身不是线程安全的在多线程场景下直接共用一个实例会偶发连接错乱、报错“连接已关闭”之类的问题。官方给的标准解法是使用SqlSugarScopepublic class DbContext { public static SqlSugarScope GetInstance() { return new SqlSugarScope(new ConnectionConfig() { DbType DbType.SqlServer, ConnectionString ...., IsAutoCloseConnection true, InitKeyType InitKeyType.Attribute }); } }SqlSugarScope在内部做了线程隔离同一个单例在多线程环境里用起来是安全的而且它还支持在作用域内共享一个连接做事务这对上位机多线程场景几乎是标配。我接手过的不少项目里有人把SqlSugarClient用成了单例高并发下时不时冒出偶发异常换成SqlSugarScope后问题直接消失。5.3 事务好写但坑在全异步SqlSugar的事务写法很直接try { db.Ado.BeginTran(); db.Insertable(record1).ExecuteCommand(); db.Updateable(record2).ExecuteCommand(); db.Ado.CommitTran(); } catch { db.Ado.RollbackTran(); throw; }但要注意在异步方法里如果用同一个SqlSugarScope实例又同时开了多个并行任务执行各自的事务事务上下文就会乱掉。正确的做法是每个任务用独立的SqlSugarScope实例或者在作用域里创建这样事务中间状态互不干扰。上位机里同时采集多个设备数据各自写入各自的事务用这个思路就能把事务边界隔离干净。5.4 高频写入的队列设计别让数据库线程被打满最后聊一个我在现场真实遇到的运维问题设备数据采集频率高了之后如果采集线程直接一条条写库数据库负载会一路飙升界面上还会出现卡顿。我的处理方式是在中间加一个“写入缓冲队列”采集线程把数据先丢进内存队列ConcurrentQueueT或者ChannelT。后台单独一个“写库线程”定时批量消费比如每3秒或者积攒到1000条时用Insertable(list).ExecuteCommandBulkCopy()批量写一次。写完清空队列如果队列满了还可以做丢弃最老数据等策略确保写入频率恒定。这个模式下数据库的写入压力从“每秒几十次小Insert”变成“每几秒一次大BulkCopy”整体性能提升非常明显。这也是我在实际上位机项目里觉得SqlSugar最能“救场”的地方——批量接口设计得好队列策略就好落地。6. 三年下来SqlSugar最值得记住的坑位清单最后把我的“踩坑清单”直接放出来都是实际项目中碰到过的附上解决办法方便大家对照自查。问题现象根因分析解决方案误删全表数据Deleteable()没有带Where条件直接执行了全表删除上线前在开发环境反复确认删除语句关键表用Where条件限制正式环境配置数据库备份枚举字段写入变数字枚举默认按数值保存老系统需要字符串状态值实体属性上加SugarColumn(ColumnDataType varchar(20))枚举转换用自定义转换器SQLite连接打不开连接字符串里的路径是相对路径运行时当前目录不同显式指定Data Source为绝对路径用Path.Combine拼好表存在却报“表不存在”实体类名与库表名大小写不匹配部分数据库大小写敏感在实体类上显式加[SugarTable(实际表名)]不要依赖默认转换异步事务报错多个异步操作共用了同一个事务连接每个作用域使用独立的SqlSugarScope事务只在同一个作用域内共用分页数据重复/漏数据分页查询没有排序强制在分页前加OrderBy养成习惯大批量Update很慢一条条Updateable执行改用Updateable(list).ExecuteCommand()InitTables后字段没更新CodeFirst只会新增字段不会改已有字段类型生产环境用SQL脚本变更表结构CodeFirst只用于初始建表其中误删全表这个坑我必须单独多说一句。SqlSugar的Deleteable()如果不带条件就是全表删除。代码review和开发规范里最好明确规定删除操作必须显式写出Where条件。这是用ORM最基本的安全底线。还有一个容易被忽视的问题实体类字段定义了decimal类型插入SQLite时精度会丢失。SQLite本身对decimal支持不佳如果项目用了SQLite做本地存储金额、浮点数据要么用double要么把精度放大存成long以分为单位等在选型阶段就得考虑清楚。再分享一个我个人的偏好实体类的属性定义尽量和数据库字段一一对应别用“一个属性兜底所有场景”的思路。ES、Redis、Sqlite、SqlServer混用的项目里实体类统一设计反而迁移成本最低。SqlSugar这个库我前后用了三年多从最开始简单的增删改查到后来在大数据量采集写入、复杂联表报表里派上用场整体体验是稳定的。它对C#上位机开发者来说最大的价值不是省了那几行SQL而是让数据库访问层变成了一块可以长期复用的稳定地基。如果你正在工控或者桌面端项目里纠结数据库访问方案SqlSugar值得纳入考量。
C#上位机数据库访问底层重构：SqlSugar实战经验与踩坑指南
做C#上位机这几年数据库操作这一块我换过不少写法。早年用ADO.NETSQL写了一大堆不说碰到SqlServer、SQLite、MySQL来回切换的时候光改连接字符串和方言语法就能折腾一下午后来试过EF Core又重又慢工控机上跑兼容性也一般。直到接触SqlSugar才算是把数据库层的代码稳定下来了。这篇文章不打算讲百科式的API罗列就围绕我在实际项目里怎么用它、踩了哪些坑、哪些功能真正帮了大忙写点能直接拿去用的东西。1. 为什么在多种C# ORM里我最终选了SqlSugar1.1 从ADO.NET硬写SQL到ORM不是偷懒是为了少犯错最早我也是纯ADO.NET派SqlConnection打开、SqlCommand拼SQL、DataTable接结果一条流水线写得滚瓜烂熟。但真正到了项目后期问题全冒出来了字段改动后手写SQL很容易漏改。表结构从A改成B的时候代码里的SELECT *和INSERT INTO改不全运行起来才报错测试成本特别高。数据量上来之后DataTable在内存里的开销很大。上位机软件本来就要长期跑动不动几十万行数据塞内存GC压力一上来界面卡顿跟着就来了。数据库切换几乎是“伤筋动骨”。厂里原本用SqlServer测试机上想换SQLiteSQL语句里带了一堆GETDATE()、WITH(NOLOCK)改起来那叫一个痛苦。ORM解决的不只是“少写代码”这么简单它强制你把“数据结构”和“数据访问逻辑”分开。实体类定义好之后字段变更在编译期就能发现至少不会出现“改库没改代码”的低级事故。1.2 EF Core和Dapper为什么不那么顺手我并不是没试过EF Core。装包、建DbContext、写迁移一套流程下来确实规范但工控场景里有个很现实的问题EF Core太重了。启动时要反射扫描、初始化模型缓存工控机配置普遍不上台面加载速度肉眼可见地慢。更重要的是EF Core的复杂查询一旦写不好生成的SQL绕来绕去调试起来头大。对上位机这种“要稳定、要快、要轻量”的场景来说它更偏向大型Web系统。Dapper是个好库轻量而且性能高但它的定位是“micro ORM”——SQL还是得你自己写只是帮你执行和映射。如果项目里有一堆复杂的联表查询、分页、动态条件拼接Dapper给不了太多帮助等于还是半只脚踩在ADO.NET里。SqlSugar恰好卡在中间比Dapper封装全比EF Core轻量文档全中文社区活跃度高。尤其在国内工控、桌面端项目里SqlSugar的出镜率相当高遇到问题一搜就有解决方案。1.3 工控场景下的选型标准我做上位机项目时对数据库层有非常具体的诉求这也是我最终选择SqlSugar的直接原因诉求说明SqlSugar的实际表现支持多数据库交付到现场后客户可能用SqlServer、MySQL、Oracle甚至SQLite内置多种DbType连接配置切换基本只改一行长期稳定运行软件经常7x24小时挂机连接管理不能出岔子IsAutoCloseConnection机制和连接池策略都算成熟高频写入优化采集数据频繁单条Insert撑不住自带BulkCopy、BulkMerge批量写入处理百万级写入有余力快速开发迭代上位机需求变化多不能把时间耗在SQL上实体映射加Lambda查询业务代码量下降一个量级可维护性后期接手的同事能看懂查询表达式即查即得不需要翻一大段SQL字符串2. 五分钟搭好基础连接配置与实体映射里的坑2.1 最小可用的SqlSugarClient不管你是.NET Framework还是.NET Core先用NuGet把包装上。新版直接用SqlSugarCore就行dotnet add package SqlSugarCore然后写一个最基础的工具类public class DbContext { public static SqlSugarClient GetInstance() { SqlSugarClient db new SqlSugarClient(new ConnectionConfig() { DbType DbType.SqlServer, ConnectionString Serverlocalhost;DatabaseDeviceDB;User Idsa;Password123456;, IsAutoCloseConnection true, InitKeyType InitKeyType.Attribute }); return db; } }ConnectionConfig里有几个参数很多人第一次用的时候看都不看就往下写后面出了问题才回头补功课我逐个说下DbType数据库类型把DbType.SqlServer换成DbType.MySql连接串一换代码基本不用动。这是SqlSugar最实在的一个优势。IsAutoCloseConnection默认是false建议开发阶段直接设为true。它的作用是每次执行完SQL后自动关闭连接避免你忘了Close()导致连接池耗尽。后面讲多线程高频读写的时候我会专门说明这个参数在大批量事务场景下要怎么配合。InitKeyType.Attribute告诉框架以实体类上的特性为主键、自增列的判断依据。还有一种InitKeyType.SystemTable是读取数据库表结构来判断主键不过那要额外查系统表没必要。2.2 实体类里那些不起眼的特性实体映射是ORM的基石SqlSugar用SugarTable和SugarColumn两个特性来做映射。我见过很多新手把数据库字段直接声明成public属性就完事结果遇到字段名对不上、主键不自增、不想入库的字段被写进去等问题非常折腾。一个常见做法是这样[SugarTable(device_info)] public class DeviceInfo { [SugarColumn(IsPrimaryKey true, IsIdentity true)] public int Id { get; set; } [SugarColumn(ColumnName device_name)] public string DeviceName { get; set; } [SugarColumn(ColumnName create_time)] public DateTime CreateTime { get; set; } [SugarColumn(IsIgnore true)] public string TempData { get; set; } }这里值得注意的三个点IsPrimaryKey和IsIdentity必须配对设置否则做更新操作时SqlSugar找不到主键条件容易生成全表更新SQL。ColumnName用来把数据库里的下划线命名映射成C#的驼峰命名。很多老系统的表字段是DEVICE_NAME这种风格实体里写成DeviceName通过ColumnName对上。IsIgnore标记的字段不会参与数据库读写。比如你实体里存了一个只是界面展示用的临时字段不标记的话SqlSugar会默认把它当成一个数据库列轻则报列不存在重则自动建表时多建一列。2.3 CodeFirst同步表结构的正确姿势SqlSugar支持从实体类自动建表db.CodeFirst.InitTables(typeof(DeviceInfo));这个功能做原型验证很好用部署到现场后新增一张配置表直接跑一行代码就把表建出来了。但有个大坑InitTables只会“加”字段不会“删”字段也不会主动帮你“改”字段类型。你改了实体的属性类型同步表结构时数据库那边没反应最容易出问题的是把int改成long、string加长度数据库里存的还是旧定义。所以在正式环境里我一般只在开发机或者初始化阶段跑一次表结构同步线上变更走脚本绝不能依赖CodeFirst。3. 查询的日常与进阶从WhereIF到联表分页3.1 表达式查询背后的门道SqlSugar最常用的入口是QueryableT()。比如查所有状态正常的设备var list db.QueryableDeviceInfo() .Where(x x.Status 1) .ToList();这段代码看起来就是普通Lambda实际上SqlSugar内部把它拆成了表达式树再翻译成对应的SQL方言。这也是为什么同样的代码可以跑在SqlServer和MySQL上——你不是在写SQL而是在用C#表达式描述查询逻辑。在写表达式时尽量别用ToString()、DateTime.Parse这类C#方法表达式树翻译器未必认得最好直接用可翻译的写法比如x.CreateTime DateTime.Now.AddDays(-1)是可以的x.CreateTime.ToString()就不一定翻译得过来。3.2 动态拼条件上位机参数查询面板的利器上位机界面里最常见的场景是界面上有一堆筛选条件用户爱填哪个填哪个不填的默认不过滤。如果用字符串拼SQL先判断再拼接很容易拼出语法错误甚至引来注入问题。SqlSugar提供了WhereIF写法非常丝滑var query db.QueryableDeviceInfo() .WhereIF(!string.IsNullOrEmpty(deviceName), x x.DeviceName.Contains(deviceName)) .WhereIF(status.HasValue, x x.Status status.Value) .WhereIF(startTime.HasValue, x x.CreateTime startTime.Value) .WhereIF(endTime.HasValue, x x.CreateTime endTime.Value);这段代码的语义是条件成立才追加过滤。我实际用下来最大的感受是查询面板再怎么变查询方法改动量都很小而且不会出现SQL关键字漏掉导致的语法错误。WhereIF的第一个参数是bool只要你能写出这个bool过滤条件就能随意组合。3.3 分页与排序不用再手写ROW_NUMBER()老的SQL写法里分页基本就是ROW_NUMBER()或者OFFSET FETCHSqlServer和MySQL语法还不一样。SqlSugar把分页封装成了ToPageListAsync配合排序表达式直接一条链子写下来var page await db.QueryableDeviceInfo() .Where(x x.Status 1) .OrderBy(x x.CreateTime, OrderByType.Descending) .ToPageListAsync(pageIndex, pageSize); int totalCount page.TotalCount; var list page.Items;返回值是PageModelTTotalCount和Items都帮你装好了不用再单独写一条SELECT COUNT(*)。这里要提一个细节分页查询一定要带OrderBy。没有排序的分页是“不稳定分页”——用户在翻页过程中数据顺序可能变化导致某条记录重复出现或者丢失。这个坑我踩过一次后来养成了条件反射只要分页必然先排序。3.4 联表查询LeftJoin设备主表和配置表设备信息一般拆成主表和配置表查询的时候又要把它们合到一起。SqlSugar的联表查询写起来比较接近SQL直觉var list await db.QueryableDeviceInfo() .LeftJoinDeviceConfig((d, c) d.Id c.DeviceId) .Where(d d.Status 1) .Select((d, c) new DeviceInfoView { DeviceName d.DeviceName, ConfigContent c.ConfigContent, UpdateTime c.UpdateTime }) .ToListAsync();LeftJoinDeviceConfig后面的Lambda就是联表条件Select里指定要返回的字段。这里要注意的是Select别用select *的习惯只取实际需要的列否则联表结果会把两张表的全部字段都查出来数据量大时性能差异非常明显。3.5 子查询与导航查询SqlFunc的巧妙用法有时候一个子查询就能解决的事没必要join。比如要查“有有效配置的设备”我用SqlFunc.Subqueryablevar list await db.QueryableDeviceInfo() .Where(d SqlFunc.SubqueryableDeviceConfig() .Where(c c.DeviceId d.Id c.IsValid 1) .Any()) .ToListAsync();这种写法生成的SQL就是EXISTS (SELECT 1 FROM ...)可读性和执行效率都不错。SqlSugar还提供了导航查询Navi可以直接通过实体属性导航关联数据不过我个人倾向在查询层用Select显式指定因为导航查询默认会加载全部关联字段而且延迟加载行为容易让人迷惑。上位机项目里“查询逻辑明确”比“代码写得短”更重要。4. 存储过程与大数据写入两种真正的“重武器”4.1 SqlSugar调用存储过程这一步很多老项目都在用Web项目里存储过程已经不多见了但工业现场的老系统完全不愁这个——厂里的MES、SCADA、DCS系统后台一堆业务逻辑都封装在存储过程里。上位机作为前端经常需要直接调这些存储过程拿数据。这时候SqlSugar的Ado直接用起来var dt db.Ado.UseStoredProcedure().GetDataTable(sp_GetDeviceHistory, new SugarParameter(deviceId, deviceId), new SugarParameter(startTime, startTime), new SugarParameter(endTime, endTime));几个细节UseStoredProcedure()是必须的否则SqlSugar会把存储过程名当成普通SQL去执行直接语法报错。参数类型用SugarParameter包装而不是SqlParameter因为要适配多种数据库。如果存储过程有返回值或output参数用SugarParameter的Direction属性设置比如new SugarParameter(outCount, 0) { Direction ParameterDirection.Output }执行完再读Value。还有一点是调用存储过程时如果涉及事务一定要把Ado和事务绑定在一起后面讲多线程那部分会详细说。4.2 批量写入一万条数据别一条一条Insert上位机采集的数据经常是满屏好几万条记录往库里灌。如果还在循环里一条条Insertable不仅慢还容易把数据库连接搞得压力很大。SqlSugar提供了原生的批量插入ListDeviceRecord records GetRecordsFromBuffer(); var result db.Insertable(records).ExecuteCommandBulkCopy();ExecuteCommandBulkCopy对应的就是SqlServer的SqlBulkCopy接口底层走的是大数据批量通道。我以前用SqlBulkCopy得手动建DataTable、逐列映射现在直接传实体集合就完事。实测下来在普通工控机上写入一万条记录从原来一条条Insert的十几秒降到了几秒以内这个差距在现场非常明显。需要留意的是ExecuteCommandBulkCopy不会帮你自动维护主键如果表有自增主键插入后你可能拿不到新生成的ID。要回填主键得用Insertable(list).ExecuteReturnIdentity()。4.3 BulkMerge更新与插入的天然合并现场还有一种很常见的场景采集数据带状态记录不存在就插入存在就更新。用SqlSugar的BulkMerge来做一条链子解决db.Storageable(records) .WhereColumns(x x.Id) // 指定判断重复的列 .ToStorage();这里解释一下Storageable的机制它把实体集合先做一次“对比分析”根据主键或指定列判断每条记录是“该插入”还是“该更新”然后可以分别获取insertList和updateList再做对应操作。这个方法在批处理现场数据时特别好用不用自己先查一次再去分别Insert和Update。用Storageable还有一个额外好处它可以返回“哪些数据有变化”方便做增量日志。具体用法可以看官方文档我只说一句——这类批处理接口才真正体现了ORM不是为了写SQL方便而是为了让你少写几十行业务逻辑。5. 多线程与高频读写的稳定性实践5.1 连接管理IsAutoCloseConnection开还是关在工控上位机里界面线程和采集线程往往是同时存在的。采集线程在后台不断写库UI线程时不时要读数据库刷新画面这就对连接的管理能力提出了要求。IsAutoCloseConnection false时连接会长时间占用配合连接池在压力大时容易打满IsAutoCloseConnection true时每次操作短连接、自动释放对上位机这种“频繁但不重”的读写模式更合适。但开头的“坑”也很明确如果在一个事务里框架本来依赖同一个连接你把IsAutoCloseConnection设为true事务可能在中途就断掉。所以我的做法是常规查询和单条操作保持true进入事务时显式BeginTran让事务期间连接一直保持打开结束后再CommitTran。5.2 SqlSugarClient不是线程安全的改用SqlSugarScope这是一个非常容易炸雷的地方。SqlSugarClient实例本身不是线程安全的在多线程场景下直接共用一个实例会偶发连接错乱、报错“连接已关闭”之类的问题。官方给的标准解法是使用SqlSugarScopepublic class DbContext { public static SqlSugarScope GetInstance() { return new SqlSugarScope(new ConnectionConfig() { DbType DbType.SqlServer, ConnectionString ...., IsAutoCloseConnection true, InitKeyType InitKeyType.Attribute }); } }SqlSugarScope在内部做了线程隔离同一个单例在多线程环境里用起来是安全的而且它还支持在作用域内共享一个连接做事务这对上位机多线程场景几乎是标配。我接手过的不少项目里有人把SqlSugarClient用成了单例高并发下时不时冒出偶发异常换成SqlSugarScope后问题直接消失。5.3 事务好写但坑在全异步SqlSugar的事务写法很直接try { db.Ado.BeginTran(); db.Insertable(record1).ExecuteCommand(); db.Updateable(record2).ExecuteCommand(); db.Ado.CommitTran(); } catch { db.Ado.RollbackTran(); throw; }但要注意在异步方法里如果用同一个SqlSugarScope实例又同时开了多个并行任务执行各自的事务事务上下文就会乱掉。正确的做法是每个任务用独立的SqlSugarScope实例或者在作用域里创建这样事务中间状态互不干扰。上位机里同时采集多个设备数据各自写入各自的事务用这个思路就能把事务边界隔离干净。5.4 高频写入的队列设计别让数据库线程被打满最后聊一个我在现场真实遇到的运维问题设备数据采集频率高了之后如果采集线程直接一条条写库数据库负载会一路飙升界面上还会出现卡顿。我的处理方式是在中间加一个“写入缓冲队列”采集线程把数据先丢进内存队列ConcurrentQueueT或者ChannelT。后台单独一个“写库线程”定时批量消费比如每3秒或者积攒到1000条时用Insertable(list).ExecuteCommandBulkCopy()批量写一次。写完清空队列如果队列满了还可以做丢弃最老数据等策略确保写入频率恒定。这个模式下数据库的写入压力从“每秒几十次小Insert”变成“每几秒一次大BulkCopy”整体性能提升非常明显。这也是我在实际上位机项目里觉得SqlSugar最能“救场”的地方——批量接口设计得好队列策略就好落地。6. 三年下来SqlSugar最值得记住的坑位清单最后把我的“踩坑清单”直接放出来都是实际项目中碰到过的附上解决办法方便大家对照自查。问题现象根因分析解决方案误删全表数据Deleteable()没有带Where条件直接执行了全表删除上线前在开发环境反复确认删除语句关键表用Where条件限制正式环境配置数据库备份枚举字段写入变数字枚举默认按数值保存老系统需要字符串状态值实体属性上加SugarColumn(ColumnDataType varchar(20))枚举转换用自定义转换器SQLite连接打不开连接字符串里的路径是相对路径运行时当前目录不同显式指定Data Source为绝对路径用Path.Combine拼好表存在却报“表不存在”实体类名与库表名大小写不匹配部分数据库大小写敏感在实体类上显式加[SugarTable(实际表名)]不要依赖默认转换异步事务报错多个异步操作共用了同一个事务连接每个作用域使用独立的SqlSugarScope事务只在同一个作用域内共用分页数据重复/漏数据分页查询没有排序强制在分页前加OrderBy养成习惯大批量Update很慢一条条Updateable执行改用Updateable(list).ExecuteCommand()InitTables后字段没更新CodeFirst只会新增字段不会改已有字段类型生产环境用SQL脚本变更表结构CodeFirst只用于初始建表其中误删全表这个坑我必须单独多说一句。SqlSugar的Deleteable()如果不带条件就是全表删除。代码review和开发规范里最好明确规定删除操作必须显式写出Where条件。这是用ORM最基本的安全底线。还有一个容易被忽视的问题实体类字段定义了decimal类型插入SQLite时精度会丢失。SQLite本身对decimal支持不佳如果项目用了SQLite做本地存储金额、浮点数据要么用double要么把精度放大存成long以分为单位等在选型阶段就得考虑清楚。再分享一个我个人的偏好实体类的属性定义尽量和数据库字段一一对应别用“一个属性兜底所有场景”的思路。ES、Redis、Sqlite、SqlServer混用的项目里实体类统一设计反而迁移成本最低。SqlSugar这个库我前后用了三年多从最开始简单的增删改查到后来在大数据量采集写入、复杂联表报表里派上用场整体体验是稳定的。它对C#上位机开发者来说最大的价值不是省了那几行SQL而是让数据库访问层变成了一块可以长期复用的稳定地基。如果你正在工控或者桌面端项目里纠结数据库访问方案SqlSugar值得纳入考量。
