从零开始：用SugarColumn和SugarORM构建你的第一个C#数据库应用

从零开始用SugarColumn和SugarORM构建你的第一个C#数据库应用当你第一次接触数据库应用开发时可能会被繁琐的SQL语句和复杂的连接管理搞得晕头转向。这时候ORM对象关系映射工具就像一位贴心的助手帮你把面向对象的代码和关系型数据库之间的鸿沟轻松跨越。在C#生态中SugarORM以其轻量级和易用性脱颖而出特别适合刚入门的开发者快速上手。SugarColumn作为SugarORM中的核心特性之一让你能够通过简单的属性标注就能精细控制实体类与数据库表之间的映射关系。想象一下你不再需要手动编写创建表的SQL语句也不再需要担心字段类型不匹配的问题——这一切都可以通过几行清晰的C#代码来完成。本文将带你从零开始一步步构建一个完整的C#数据库应用。无论你是刚接触C#的新手还是有一定经验但想尝试SugarORM的开发者都能从中获得实用的知识和技巧。我们会从环境配置开始逐步深入到实体类定义、CRUD操作等核心内容最后还会分享一些实际开发中的小技巧。1. 环境准备与基础配置在开始使用SugarORM之前我们需要确保开发环境已经准备就绪。对于C#开发来说Visual Studio无疑是最强大的IDE选择但如果你更喜欢轻量级的工具Visual Studio Code配合C#插件也能很好地完成任务。首先创建一个新的C#控制台应用程序项目。在Visual Studio中可以通过文件→新建→项目然后选择控制台应用(.NET Core)模板来完成这一步骤。给项目取个有意义的名字比如FirstSugarApp。接下来我们需要通过NuGet包管理器添加SugarORM的依赖。在解决方案资源管理器中右键点击项目选择管理NuGet程序包然后搜索SqlSugarCoreSugarORM的核心包。目前最新稳定版本是5.x系列点击安装即可。安装完成后基本的项目结构应该如下所示FirstSugarApp/ ├── Program.cs ├── FirstSugarApp.csproj为了验证安装是否成功可以在Program.cs文件中添加以下引用using SqlSugar;如果代码没有报错说明SugarORM已经成功引入到项目中。接下来我们需要配置数据库连接。SugarORM支持多种数据库包括SQL Server、MySQL、PostgreSQL等。这里我们以SQLite为例因为它不需要额外的服务器配置非常适合学习和快速原型开发。首先添加SQLite的NuGet包再次打开NuGet包管理器搜索Microsoft.Data.Sqlite安装最新稳定版本然后在Program.cs中初始化SugarORM的SqlSugarClientvar db new SqlSugarClient(new ConnectionConfig() { ConnectionString Data Source./firstSugarDb.db, DbType DbType.Sqlite, IsAutoCloseConnection true, InitKeyType InitKeyType.Attribute });这段代码创建了一个到SQLite数据库的连接数据库文件将保存在项目目录下名为firstSugarDb.db的文件中。如果文件不存在SugarORM会自动创建它。提示在实际项目中建议将连接字符串放在配置文件中而不是硬编码在代码里。这里为了演示简化了流程。2. 定义实体类与SugarColumn详解有了数据库连接后下一步就是定义我们的数据模型。在ORM中我们通过创建实体类来映射数据库中的表。SugarORM使用C#的特性(Attribute)来标记这些映射关系其中SugarColumn是最常用的特性之一。让我们创建一个简单的用户管理系统的数据模型。首先在项目中添加一个名为Models的文件夹然后创建一个新的类文件User.cs。using SqlSugar; namespace FirstSugarApp.Models { [SugarTable(user)] // 指定映射到的表名 public class User { [SugarColumn(IsPrimaryKey true, IsIdentity true)] public int Id { get; set; } [SugarColumn(ColumnName user_name, Length 50)] public string Name { get; set; } [SugarColumn(IsNullable true)] public int? Age { get; set; } [SugarColumn(ColumnDataType varchar(100))] public string Email { get; set; } [SugarColumn(IsIgnore true)] public string TemporaryNote { get; set; } } }这个简单的User类展示了SugarColumn的多种用法IsPrimaryKey标记该属性为主键IsIdentity表示主键是自增的ColumnName指定数据库中的列名与属性名不同Length设置字符串字段的最大长度IsNullable允许字段为nullColumnDataType精确控制数据库中的列类型IsIgnore该属性不会被映射到数据库SugarColumn还支持更多参数下面是一个更全面的参数说明表格参数名类型说明默认值IsPrimaryKeybool是否为主键falseIsIdentitybool是否自增falseColumnNamestring数据库列名属性名ColumnDescriptionstring列描述nullColumnDataTypestring数据库类型自动推断Lengthint字段长度0IsNullablebool是否可为nullfalseIsIgnorebool是否忽略映射falseDecimalDigitsint小数位数0OldColumnNamestring旧列名(用于重命名)nullIsOnlyIgnoreInsertbool仅忽略插入falseIsOnlyIgnoreUpdatebool仅忽略更新false在实际开发中你不需要为每个属性都设置所有参数。SugarORM有很智能的默认行为大多数情况下你只需要标记主键和需要特殊处理的字段即可。3. 数据库表创建与基本CRUD操作有了实体类定义后我们可以让SugarORM帮我们创建对应的数据库表。这比手动编写SQL语句要简单和安全得多。在Program.cs的Main方法中添加以下代码// 创建数据库表 db.CodeFirst.InitTables(typeof(User));这行代码会根据User类的定义在数据库中创建对应的表。如果表已经存在SugarORM会比较模型和现有表的结构差异必要时会提示你是否要执行迁移操作。注意在生产环境中直接修改数据库结构需要谨慎。SugarORM提供了更安全的迁移工具但对于初学者和小型项目CodeFirst.InitTables已经足够。现在我们可以开始进行最基本的CRUD创建、读取、更新、删除操作了。下面是一些基本示例插入数据// 插入单条记录 var userId db.Insertable(new User() { Name 张三, Age 25, Email zhangsanexample.com }).ExecuteReturnIdentity(); // 批量插入 var userList new ListUser { new User { Name 李四, Age 30, Email lisiexample.com }, new User { Name 王五, Age 28, Email wangwuexample.com } }; db.Insertable(userList).ExecuteCommand();查询数据// 查询所有记录 var allUsers db.QueryableUser().ToList(); // 条件查询 var youngUsers db.QueryableUser() .Where(u u.Age 30) .ToList(); // 分页查询 var pageUsers db.QueryableUser() .Where(u u.Age 20) .ToPageList(1, 10, ref totalCount);更新数据// 更新单条记录 db.Updateable(new User() { Id 1, Name 张三丰, Age 26 }).ExecuteCommand(); // 条件更新 db.UpdateableUser() .SetColumns(u new User { Age u.Age 1 }) .Where(u u.Age 30) .ExecuteCommand();删除数据// 根据主键删除 db.DeleteableUser().In(1).ExecuteCommand(); // 条件删除 db.DeleteableUser() .Where(u u.Age 60) .ExecuteCommand();这些基本操作涵盖了大多数日常开发需求。SugarORM的API设计非常直观即使没有太多SQL知识也能轻松理解这些操作对应的数据库行为。4. 高级特性与性能优化掌握了基本操作后让我们看看SugarORM的一些高级特性这些功能可以帮助你编写更高效、更简洁的代码。事务处理数据库事务对于保证数据一致性至关重要。SugarORM提供了简单的事务支持try { db.Ado.BeginTran(); // 一系列数据库操作 db.Insertable(new User { Name 事务测试1 }).ExecuteCommand(); db.Insertable(new User { Name 事务测试2 }).ExecuteCommand(); db.Ado.CommitTran(); } catch (Exception) { db.Ado.RollbackTran(); throw; }复杂查询SugarORM支持复杂的查询构建几乎可以满足所有SQL查询需求// 多表联查 var query db.QueryableUser, Order((u, o) new JoinQueryInfos( JoinType.Left, u.Id o.UserId)) .Where((u, o) u.Age 20) .Select((u, o) new { u.Name, o.OrderNo }) .ToList(); // 分组查询 var ageGroups db.QueryableUser() .GroupBy(u u.Age) .Select(u new { Age u.Age, Count SqlFunc.AggregateCount(u.Id) }) .ToList();性能优化技巧批量操作对于大量数据操作总是使用批量方法而非循环单条操作异步支持所有主要方法都有异步版本适合Web应用查询过滤器可以定义全局过滤条件如软删除二级缓存减少重复查询对数据库的压力// 异步操作示例 var asyncUsers await db.QueryableUser() .Where(u u.Age 20) .ToListAsync(); // 使用查询过滤器 db.QueryFilter.Add(new TableFilterItemUser(u u.IsDeleted false)); // 之后的所有查询都会自动加上这个条件实体关系映射SugarORM支持一对一、一对多等关系映射[SugarTable(order)] public class Order { [SugarColumn(IsPrimaryKey true, IsIdentity true)] public int Id { get; set; } public string OrderNo { get; set; } [SugarColumn(IsNullable false)] public int UserId { get; set; } [Navigate(NavigateType.OneToOne, nameof(UserId))] public User User { get; set; } }这样查询订单时可以自动加载关联的用户信息var orders db.QueryableOrder() .Includes(o o.User) // 自动加载User .ToList();5. 实际开发中的经验分享在实际项目中使用SugarORM一段时间后我积累了一些值得分享的经验实体类设计的最佳实践为所有实体添加一个基类包含公共字段如Id、CreateTime等合理使用partial类将大型实体拆分到多个文件为常用查询条件创建扩展方法public abstract class EntityBase { [SugarColumn(IsPrimaryKey true, IsIdentity true)] public int Id { get; set; } [SugarColumn(ColumnName create_time)] public DateTime CreateTime { get; set; } DateTime.Now; [SugarColumn(ColumnName update_time)] public DateTime UpdateTime { get; set; } DateTime.Now; } public partial class User : EntityBase { // 基础字段 } public static class UserQueryExtensions { public static ISugarQueryableUser ActiveUsers(this ISugarQueryableUser query) { return query.Where(u u.IsActive); } }处理数据库迁移对于生产环境直接使用CodeFirst.InitTables可能不够安全。建议开发环境可以使用InitTables快速迭代测试和生产环境使用迁移工具重大变更考虑手动编写迁移脚本调试与日志SugarORM提供了详细的SQL日志功能对调试非常有帮助db.Aop.OnLogExecuting (sql, pars) { Console.WriteLine(sql); Console.WriteLine(string.Join(,, pars?.Select(p p.ParameterName p.Value))); };性能监控对于关键业务操作监控SQL执行时间db.Aop.OnLogExecuting (sql, pars) { Stopwatch sw new Stopwatch(); sw.Start(); }; db.Aop.OnLogExecuted (sql, pars) { sw.Stop(); Console.WriteLine($执行时间{sw.ElapsedMilliseconds}ms); };在最近的一个项目中我们使用SugarORM处理了每天数十万次的数据库操作通过合理的优化和缓存策略系统保持了良好的响应速度。特别是在处理复杂报表查询时SugarORM的灵活查询构建器让我们能够快速调整查询逻辑而无需重写大量SQL代码。