1. 项目概述为什么选择SqlSugar与SQLite作为入门组合如果你刚开始接触.NET开发或者想找一个轻量、易上手的数据库操作方案那么SqlSugar搭配SQLite绝对是一个被低估的黄金组合。我最初接触这个组合是在一个需要快速原型验证的小工具项目里当时的需求很简单需要一个零配置、单文件、无需安装数据库服务的存储方案同时希望用上ORM对象关系映射来避免手写繁琐的SQL。几番对比下来SqlSugarSQLite以近乎“开箱即用”的体验胜出。简单来说SqlSugar是一个功能强大且性能优异的国产.NET ORM框架它的API设计非常人性化链式调用写起来很流畅。而SQLite是一个进程内的、无服务器的、零配置的、事务性的SQL数据库引擎整个数据库就是一个.db文件拷贝、备份、部署都极其方便。这两者结合对于桌面应用、小型Web应用、移动端应用或者需要嵌入式数据库的场景来说简直是“天作之合”。你不需要在机器上安装任何数据库软件只需要引入几个NuGet包就能立刻开始进行数据的增删改查这种快速启动的成就感对初学者尤其友好。本篇入门指南我将带你从零开始一步步搭建环境完成基础的CRUD创建、读取、更新、删除操作并分享一些我初期使用时遇到的“坑”和解决技巧。我们的目标是看完之后你就能在自己的项目中用起来。2. 环境准备与项目搭建2.1 开发环境与工具选型工欲善其事必先利其器。首先明确我们的技术栈.NET 6 (或.NET Core 3.1) C#。我强烈建议使用Visual Studio 2022或JetBrains Rider作为IDE它们对NuGet包管理和现代C#特性的支持最好。接下来是核心的NuGet包我们需要安装两个SqlSugarCore这是SqlSugar ORM框架的核心包。System.Data.SQLite.Core这是SQLite的ADO.NET提供程序。注意选择Core版本以确保在.NET Core/ .NET 5环境下的兼容性。安装方式很简单在Visual Studio的“程序包管理器控制台”中执行以下命令或者在解决方案资源管理器中右键项目“管理NuGet程序包”并搜索安装Install-Package SqlSugarCore Install-Package System.Data.SQLite.Core这里有个关键点System.Data.SQLite.Core包会自动为你部署对应平台x86/x64的SQLite本地互操作库SQLite.Interop.dll。如果你在运行时遇到“无法加载DLL ‘SQLite.Interop.dll’”的错误通常是因为部署问题。对于控制台或桌面应用确保你的生成输出目录包含这个dll对于Web应用可能需要设置“复制到输出目录”属性。2.2 初始化SqlSugar与数据库连接安装好包之后第一步是配置并初始化SqlSugar的SqlSugarClient或SqlSugarScope推荐用于依赖注入场景。我们先从最简单的控制台应用开始。首先定义一个实体类Entity它对应数据库中的一张表。假设我们要管理一个Student学生表// 学生实体类 [SugarTable(Student)] // 特性指定表名如果类名和表名一致可省略 public class Student { [SugarColumn(IsPrimaryKey true, IsIdentity true)] // 主键、自增 public int Id { get; set; } [SugarColumn(Length 50, IsNullable false)] // 长度50非空 public string Name { get; set; } public int Age { get; set; } [SugarColumn(Length 100)] public string Major { get; set; } [SugarColumn(IsNullable true)] public DateTime? EnrollmentDate { get; set; } // 可空日期 }[SugarColumn]特性非常有用可以精细控制字段属性如主键、自增、长度、是否可空等。如果不用特性SqlSugar默认会按属性名映射到同名字段并且所有属性都可空。接下来在Program.cs或主方法中配置和初始化SqlSugarClientusing SqlSugar; class Program { static void Main(string[] args) { // 1. 创建数据库连接配置 var connectionString Data Source./demo.db; // 数据库文件路径 var dbType DbType.Sqlite; // 数据库类型 // 2. 初始化SqlSugarClient // 使用ConnectionConfig var db new SqlSugarClient(new ConnectionConfig() { ConnectionString connectionString, DbType dbType, IsAutoCloseConnection true, // 自动释放连接默认为true InitKeyType InitKeyType.Attribute // 从实体特性读取主键、自增列信息 }); // 3. 创建数据库和表如果不存在 db.DbMaintenance.CreateDatabase(); // 对于SQLite此方法会检查文件是否存在不存在则创建 db.CodeFirst.InitTables(typeof(Student)); // 初始化Student表如果表不存在则创建 Console.WriteLine(数据库和表初始化完成); // ... 后续进行CRUD操作 } }注意CreateDatabase()方法在SQLite中并不是真的“创建数据库”因为SQLite的数据库就是一个文件。它的作用是检查连接字符串指定的文件路径是否存在如果不存在则在首次执行SQL时比如InitTables自动创建该文件。InitTables方法会根据你传入的实体类型检查表是否存在不存在则根据实体特性生成并执行建表SQL。这段代码跑通看到成功输出的信息你的基础环境就搭建好了。demo.db文件会在你的项目输出目录如bin/Debug/net6.0下生成。你可以用DB Browser for SQLite这样的图形化工具打开它查看表结构。3. 核心操作从零开始掌握CRUD环境搭好实体定义好我们就可以开始最核心的数据操作了。SqlSugar的API设计得很直观我们通过几个例子快速上手。3.1 新增数据Create向数据库插入新记录SqlSugar提供了Insertable方法。// 插入单条记录返回插入后的自增主键值如果存在 var studentId db.Insertable(new Student { Name 张三, Age 20, Major 计算机科学, EnrollmentDate DateTime.Now }).ExecuteReturnIdentity(); // 执行插入并返回自增ID Console.WriteLine($插入成功学生ID: {studentId}); // 批量插入 var studentList new ListStudent { new Student { Name 李四, Age 21, Major 软件工程 }, new Student { Name 王五, Age 22, Major 网络工程 } }; var affectedRows db.Insertable(studentList).ExecuteCommand(); // 执行插入返回受影响行数 Console.WriteLine($批量插入成功影响行数: {affectedRows});实操心得ExecuteReturnIdentity()通常用于需要立刻获取自增ID的场景比如插入后需要关联其他数据。ExecuteCommand()执行命令并返回受影响的行数适用于插入、更新、删除。批量插入的效率远高于循环单条插入SqlSugar内部会进行优化。对于大量数据插入还可以考虑使用BulkCopy需要商业版或分批次插入。3.2 查询数据Read查询是数据库操作中最频繁的部分SqlSugar的查询API非常灵活强大。基础查询与条件过滤// 查询所有记录 var allStudents db.QueryableStudent().ToList(); // 带条件的查询查询年龄大于20的学生 var adultStudents db.QueryableStudent() .Where(s s.Age 20) .ToList(); // 多条件组合查询年龄大于19且专业包含“工程”的学生 var engineeringStudents db.QueryableStudent() .Where(s s.Age 19 s.Major.Contains(工程)) .ToList();排序、分页与指定字段// 按年龄降序排序然后按姓名升序排序 var sortedStudents db.QueryableStudent() .OrderBy(s s.Age, OrderByType.Desc) .OrderBy(s s.Name, OrderByType.Asc) .ToList(); // 分页查询查询第2页每页5条数据 var pageIndex 2; var pageSize 5; var pagedStudents db.QueryableStudent() .OrderBy(s s.Id) // 分页必须排序 .ToPageList(pageIndex, pageSize, ref totalCount); // totalCount是总记录数需要提前声明 int totalCount 0; Console.WriteLine($第{pageIndex}页数据共{totalCount}条记录); // 只查询特定字段避免SELECT * var simpleList db.QueryableStudent() .Select(s new { s.Id, s.Name, s.Major }) // 匿名对象 .ToList(); // 或者映射到DTO public class StudentSimpleDto { public int Id { get; set; } public string Name { get; set; } } var dtoList db.QueryableStudent() .SelectStudentSimpleDto() // 指定目标类型 .ToList();联表查询虽然我们当前是单表入门但了解联表查询很有必要。假设我们还有一个Course课程表和StudentCourse选课表。var result db.QueryableStudent() .LeftJoinStudentCourse((s, sc) s.Id sc.StudentId) .LeftJoinCourse((s, sc, c) sc.CourseId c.Id) .Select((s, sc, c) new { StudentName s.Name, CourseName c.Name }) .ToList();注意Where和OrderBy等方法支持链式调用非常符合编程习惯。分页查询ToPageList必须配合OrderBy使用否则会抛出异常。对于复杂查询SqlSugar也支持原生SQL使用SqlQueryableT。3.3 更新数据Update更新操作使用Updateable方法支持更新单个实体、指定条件更新部分字段。// 方式1更新整个实体根据主键 var studentToUpdate db.QueryableStudent().Single(s s.Id 1); // 先查询出来 if (studentToUpdate ! null) { studentToUpdate.Age 23; studentToUpdate.Major 人工智能; var updateResult db.Updateable(studentToUpdate).ExecuteCommand(); } // 方式2根据条件更新指定字段更高效无需先查询 var affectedRows db.UpdateableStudent() .SetColumns(s new Student { Age s.Age 1, Major 升级专业 }) // 字段可以基于原值计算 .Where(s s.Id 2) .ExecuteCommand(); // 方式3使用对象作为条件进行更新更新非主键字段Where条件用匿名对象 var affectedRows2 db.UpdateableStudent() .SetColumns(s s.Major 新专业) .Where(s new { s.Name, s.Age }) // 根据姓名和年龄定位 .ExecuteCommand();避坑指南Updateable整个实体时默认会更新所有字段除了忽略更新的特性标记。如果你只想更新修改过的字段可以使用UpdateColumns方法或者使用SetColumns进行指定字段更新后者性能更好且更安全避免了前端传递整个对象可能带来的字段覆盖风险。3.4 删除数据Delete删除操作使用Deleteable方法支持根据主键删除、根据条件删除。// 根据主键删除 var deleteResult db.DeleteableStudent().In(1).ExecuteCommand(); // 删除Id为1的记录 // 或 var deleteResult2 db.DeleteableStudent().Where(s s.Id 1).ExecuteCommand(); // 根据条件删除批量删除 var deleteResult3 db.DeleteableStudent() .Where(s s.Age 18) // 删除年龄小于18的学生 .ExecuteCommand(); // 使用实体对象删除根据主键值 var studentToDelete new Student { Id 3 }; var deleteResult4 db.Deleteable(studentToDelete).ExecuteCommand();重要警告删除操作是不可逆的在生产环境中执行删除尤其是条件删除Where前务必先使用.ToList()或.Any()验证将要删除的数据是否正确。建议对重要数据采用逻辑删除即增加一个IsDeleted标志位通过更新操作实现而非物理删除。4. 进阶技巧与最佳实践掌握了基本的CRUD我们来看看如何让代码更健壮、更高效。这些技巧很多是我在项目中踩过坑后总结出来的。4.1 使用依赖注入DI管理SqlSugarClient在ASP.NET Core等现代应用中我们通常使用依赖注入来管理数据库上下文等资源。SqlSugar提供了SqlSugarScope来替代SqlSugarClient它内部实现了连接池和线程安全更适合单例注入。首先在Program.cs.NET 6中配置服务var builder WebApplication.CreateBuilder(args); // 从配置中读取连接字符串 var connectionString builder.Configuration.GetConnectionString(DefaultConnection); builder.Services.AddSingletonISqlSugarClient(sp { var config new ConnectionConfig { ConnectionString connectionString, DbType DbType.Sqlite, IsAutoCloseConnection true, InitKeyType InitKeyType.Attribute }; // 使用SqlSugarScope return new SqlSugarScope(config, db { // 这里可以配置AOP事件比如打印SQL日志 db.Aop.OnLogExecuting (sql, pars) { Console.WriteLine(sql); // 输出SQL语句 // 也可以使用ILogger记录到文件 }; }); }); var app builder.Build();然后在控制器或服务中通过构造函数注入使用public class StudentService { private readonly ISqlSugarClient _db; public StudentService(ISqlSugarClient db) { _db db; } public ListStudent GetAllStudents() { return _db.QueryableStudent().ToList(); } }使用SqlSugarScope的最大好处是你不需要手动处理连接的打开和关闭框架会帮你管理连接的生命周期并且在并行操作时也是安全的。4.2 利用AOP进行SQL监控与日志记录AOP面向切面编程是SqlSugar的一个强大功能允许你在SQL执行前后插入自定义逻辑最常用的就是日志记录。var db new SqlSugarScope(config, db { // 监控SQL执行前 db.Aop.OnLogExecuting (sql, pars) { // 获取原生SQL将参数替换进去 var rawSql UtilMethods.GetSqlString(db.CurrentConnectionConfig.DbType, sql, pars); Console.WriteLine($执行SQL{rawSql}); Console.WriteLine($执行时间{DateTime.Now}); // 可以将日志写入文件或数据库 // File.AppendAllText(sql.log, $[{DateTime.Now}] {rawSql}{Environment.NewLine}); }; // 监控SQL执行后可以获取执行时间 db.Aop.OnLogExecuted (sql, pars) { // 这里可以计算耗时如果耗时过长可以报警 }; // 监控错误 db.Aop.OnError (exp) { // 发生SQL错误时的处理 Console.WriteLine($SQL错误{exp.Message}); }; });实操心得在开发阶段开启SQL日志输出到控制台或调试窗口能极大方便你排查问题检查生成的SQL是否符合预期。但在生产环境要谨慎记录日志避免输出敏感信息如密码或导致日志文件过大。建议根据日志级别进行控制。4.3 实体配置的更多玩法除了基础的[SugarColumn]实体特性还有很多有用的配置。索引与唯一键[SugarTable(Student)] public class Student { [SugarColumn(IsPrimaryKey true, IsIdentity true)] public int Id { get; set; } [SugarColumn(Length 50)] public string Name { get; set; } [SugarColumn(IndexGroupNameList new string[] { Index_Age })] // 创建普通索引 public int Age { get; set; } [SugarColumn(Length 100, IsNullable false, IsUnique true)] // 创建唯一索引 public string StudentNumber { get; set; } }使用db.CodeFirst.InitTables时SqlSugar会根据这些特性创建相应的索引。忽略映射与仅插入/更新public class Student { public int Id { get; set; } public string Name { get; set; } [SugarColumn(IsIgnore true)] // 完全忽略不映射到数据库 public string FullName ${Name} (ID:{Id}); [SugarColumn(IsOnlyIgnoreInsert true)] // 仅插入时忽略更新时包含 public DateTime CreateTime { get; set; } [SugarColumn(IsOnlyIgnoreUpdate true)] // 仅更新时忽略插入时包含 public DateTime UpdateTime { get; set; } }IsOnlyIgnoreInsert和IsOnlyIgnoreUpdate在实现“创建时间”和“更新时间”自动管理时非常有用。通常CreateTime在插入时由代码赋值如DateTime.Now后续更新不再改变UpdateTime则在每次更新时刷新。4.4 事务处理确保一组操作要么全部成功要么全部失败这是事务的核心。SqlSugar的事务使用非常简单。try { db.Ado.BeginTran(); // 开始事务 // 操作1插入学生 var studentId db.Insertable(new Student{ Name赵六}).ExecuteReturnIdentity(); // 操作2为该学生插入一条课程记录假设有CourseSelection表 // 这里故意制造一个可能失败的操作 db.Insertable(new CourseSelection { StudentId studentId, CourseId 999 }).ExecuteCommand(); // 假设CourseId999不存在外键约束可能失败 db.Ado.CommitTran(); // 提交事务 Console.WriteLine(事务提交成功); } catch (Exception ex) { db.Ado.RollbackTran(); // 回滚事务 Console.WriteLine($操作失败已回滚{ex.Message}); }重要提示务必使用try-catch块包裹事务操作并在catch中执行回滚。也可以使用SqlSugarScope提供的UseTran方法它提供了更简洁的语法糖能自动处理回滚var result db.UseTran(() { // 在这里面执行多个数据库操作 db.Insertable(...).ExecuteCommand(); db.Updateable(...).ExecuteCommand(); // 如果这里抛出异常事务会自动回滚 }); if (!result.IsSuccess) // 判断事务是否成功 { Console.WriteLine($事务失败{result.ErrorMessage}); }5. 常见问题排查与调试技巧即使按照指南操作新手也难免会遇到一些问题。这里我整理了几个最常见的问题和解决方法。5.1 连接字符串与文件路径问题问题描述程序运行时抛出异常提示“无法打开数据库文件”或“no such table”。排查步骤检查文件路径Data Source./demo.db中的./代表应用程序的当前工作目录。在控制台应用中这通常是bin/Debug/net6.0在Web应用中可能是项目根目录或发布目录。使用绝对路径更可靠例如Data SourceD:/MyApp/data/demo.db。检查文件权限确保应用程序进程如IIS工作进程、你的用户账户对目标目录和文件有读写权限。检查文件是否被占用SQLite数据库文件在连接期间会被锁定。确保没有其他程序如DB Browser for SQLite、另一个你的程序实例正在打开这个.db文件。使用:memory:进行测试如果不确定是路径问题可以暂时使用内存数据库Data Source:memory:进行测试。如果内存数据库工作正常那问题肯定出在文件路径或权限上。5.2 实体与表结构映射错误问题描述查询时提示“no such column: XXX”或者插入/更新时字段值不对。排查步骤检查特性标记确认[SugarTable]和[SugarColumn]使用正确。特别是IsPrimaryKey和IsIdentity如果主键不是自增不要设置IsIdentitytrue。检查表是否创建成功首次运行InitTables后用DB Browser for SQLite打开.db文件查看表结构是否和你的实体类定义一致。注意字段类型映射如C#的string默认映射为nvarchar(255)int映射为INTEGER。启用SQL日志按照4.2节的方法启用Aop.OnLogExecuting查看实际生成的SQL语句。对比SQL中的表名、列名和数据库中的是否一致。考虑关闭列名映射规则SqlSugar默认会将PascalCase的属性名如StudentName映射为数据库的student_name蛇形命名。如果你希望严格按属性名映射可以在ConnectionConfig中设置MoreSettingsMoreSettings new ConnMoreSettings { SqlServerCodeFirstNamingConvention null, // 关闭命名约定 // 或者指定为原样映射 // PgSqlIsAutoToLower false, // IsAutoToUpper false }5.3 性能优化初步建议当数据量逐渐增大时一些不当操作会影响性能。避免SELECT *始终使用.Select()指定需要的字段尤其是表中存在TEXT或BLOB等大字段时。善用索引对经常用于WHERE、ORDER BY、JOIN条件的字段创建索引如[SugarColumn(IndexGroupNameList new[] { Index_Name })]。但索引并非越多越好它会降低插入和更新速度。批量操作如前所述批量插入Insertable(list).ExecuteCommand()比循环单条插入快得多。更新和删除也尽量通过Where条件批量处理而不是循环单条执行。分页查询列表查询一定要分页使用.ToPageList()并确保有正确的Order By。不要一次性查询几万条数据到内存中。合理使用异步方法SqlSugar提供了完整的异步API如ToListAsync(),ExecuteCommandAsync()。在ASP.NET Core等支持异步的框架中使用异步方法可以提高应用的并发吞吐量。5.4 调试工具推荐DB Browser for SQLite (SQLite官方GUI工具)免费、开源、跨平台。用于直观地查看表结构、浏览数据、执行原始SQL语句。这是排查数据相关问题不可或缺的工具。Visual Studio的服务器资源管理器如果你使用VS可以通过“视图”-“服务器资源管理器”-“数据连接”添加SQLite连接直接在IDE内查看数据。SqlSugar AOP日志这是最强大的调试工具。将生成的SQL和参数打印出来你就能清楚地知道框架到底做了什么。复杂查询时可以把生成的SQL复制到DB Browser中执行验证结果。入门阶段把上述CRUD操作练熟理解事务和依赖注入的基本用法你就能应对大多数简单的数据持久化需求了。SqlSugarSQLite这个组合的魅力在于它用极低的复杂度让你快速获得生产力而背后又有足够强大的功能支撑你应对更复杂的场景。当你需要迁移到SQL Server、MySQL等数据库时SqlSugar的绝大多数代码都可以无缝迁移只需修改连接字符串和DbType这才是ORM框架带来的最大价值之一。