2018年11月的某一天，头脑发热开启了 FreeSql 开源项目之旅，时间一晃已经四年多，当初从舒服区走向一个巨大的坑，回头一看后背一凉。四年时间从无到有，经历了数不清的日夜奋战（有人问我花了多长时间投入，答案：全职x2 + 前两年无休息，以及后面两年的持续投入）。今天 FreeSql 已经很强大，感谢第一期、第二期、第N期持续提出建议的网友。
FreeSql 现如今已经是一个稳定的版本，主要体现：
感叹：有些人说 .Net 陷入 orm 怪圈，动手的没几个，指点江山的一堆，.Net orm 真的如他们所讲的简单吗？
FreeSql 是 .Net ORM，能支持 .NetFramework4.0+、.NetCore、Xamarin、MAUI、Blazor、以及还有说不出来的运行平台，因为代码绿色无依赖，支持新平台非常简单。目前单元测试数量：6336+，Nuget下载数量：900K+。QQ群：4336577(已满)、8578575(在线)、52508226(在线)
温馨提醒：以下内容无商吹成份，FreeSql 不打诳语
为什么要重复造轮子？
FreeSql 主要优势在于易用性上，基本是开箱即用，在不同数据库之间切换兼容性比较好。作者花了大量的时间精力在这个项目，肯请您花半小时了解下项目，谢谢。FreeSql 整体的功能特性如下：
5500+个单元测试作为基调，支持10多数数据库，我们提供了通用Odbc理论上支持所有数据库，目前已知有群友使用 FreeSql 操作华为高斯、mycat、tidb 等数据库。安装时只需要选择对应的数据库实现包：
dotnet add packages FreeSql.Provider.MySql
FreeSql.Repository 是 FreeSql 项目的延申扩展类库，支持 .NETFramework4.0+、.NETCore2.0+、.NET5+、Xamarin 平台。
FreeSql.Repository 除了 CRUD 还有很多实用性功能，不防耐下心花10分钟看完。
环境1：.NET Core 或 .NET 5.0+
dotnet add package FreeSql.Repository 环境2、.NET Framework
Install-Package FreeSql.DbContext static IFreeSql fsql = new FreeSql.FreeSqlBuilder() .UseConnectionString(FreeSql.DataType.Sqlite, connectionString) .UseAutoSyncStructure(true) //自动迁移实体的结构到数据库 .Build(); //请务必定义成 Singleton 单例模式 方法1、IFreeSql 的扩展方法；
var curd = fsql.GetRepository<Topic>(); 注意：Repository 对象多线程不安全，因此不应在多个线程上同时对其执行工作。
以下为了方便测试代码演示，我们都使用方法1，fsql.GetRepository
创建新仓储实例
方法2、继承实现；
public class TopicRepository: BaseRepository<Topic, int> { public TopicRepository(IFreeSql fsql) : base(fsql, null, null) {} //在这里增加 CURD 以外的方法 } 方法3、依赖注入；
public void ConfigureServices(IServiceCollection services) { services.AddSingleton<IFreeSql>(Fsql); services.AddFreeRepository(null, this.GetType().Assembly); } //在控制器使用 public TopicController(IBaseRepository<Topic> repo) { } repo.Insert 插入数据，适配了各数据库优化执行 ExecuteAffrows/ExecuteIdentity/ExecuteInserted
1、如果表有自增列，插入数据后应该要返回 id。
var repo = fsql.GetRepository<Topic>(); repo.Insert(topic); 内部会将插入后的自增值填充给 topic.Id
2、批量插入
var repo = fsql.GetRepository<Topic>(); var topics = new [] { new Topic { ... }, new Topic { ... } }； repo.Insert(topics); 3、插入数据库时间
使用 [Column(ServerTime = DateTimeKind.Utc)] 特性，插入数据时，使用适配好的每种数据库内容，如 getutcdate()
4、插入特殊类型
使用 [Column(RereadSql = "{0}.STAsText()", RewriteSql = "geography::STGeomFromText({0},4236)")] 特性，插入和读取时特别处理
5、插入时忽略
使用 [Column(CanInsert = false)] 特性
1、只更新变化的属性
var repo = fsql.GetRepository<Topic>(); var item = repo.Where(a => a.Id == 1).First(); //此时快照 item item.Name = "newtitle"; repo.Update(item); //对比快照时的变化 //UPDATE `Topic` SET `Title` = 'newtitle' //WHERE (`Id` = 1) 2、手工管理状态
var repo = fsql.GetRepository<Topic>(); var item = new Topic { Id = 1 }; repo.Attach(item); //此时快照 item item.Title = "newtitle"; repo.Update(item); //对比快照时的变化 //UPDATE `Topic` SET `Title` = 'newtitle' //WHERE (`Id` = 1) 3、直接使用 repo.UpdateDiy，它是 IFreeSql 提供的原生 IUpdate 对象，功能更丰富
实践发现，N对1 不适合做级联保存。保存 Topic 的时候把 Type 信息也保存？我个人认为自下向上保存的功能太不可控了，FreeSql 目前不支持自下向上保存。因此下面我们只讲 OneToOne/OneToMany/ManyToMany 级联保存。至于 ManyToOne 级联保存使用手工处理，更加安全可控。
功能1：SaveMany 手工保存
完整保存，对比表已存在的数据，计算出添加、修改、删除执行。
递归保存导航属性不安全，不可控，并非技术问题，而是出于安全考虑，提供了手工完整保存的方式。
var repo = fsql.GetRepository<Type>(); var type = new Type { name = "c#", Topics = new List<Topic>(new[] { new Topic { ... } }) }; repo.Insert(type); repo.SaveMany(type, "Topics"); //手工完整保存 Topics 如：
功能2：EnableCascadeSave 仓储级联保存
DbContext/Repository EnableCascadeSave 可实现保存对象的时候，递归追朔其 OneToOne/OneToMany/ManyToMany 导航属性也一并保存，本文档说明机制防止误用。
1、OneToOne 级联保存
v3.2.606+ 支持，并且支持级联删除功能(文档请向下浏览)
2、OneToMany 追加或更新子表，不删除子表已存在的数据
var repo = fsql.GetRepository<Type>(); repo.DbContextOptions.EnableCascadeSave = true; //需要手工开启 repo.Insert(type); 向下18层的意思，比如【类型】表，下面有集合属性【文章】，【文章】下面有集合属性【评论】。
保存【类型】表对象的时候，他会向下检索出集合属性【文章】，然后如果【文章】被保存的时候，再继续向下检索出集合属性【评论】。一起做 InsertOrUpdate 操作。
3、ManyToMany 完整对比保存中间表，追加外部表
完整对比保存中间表，对比【多对多】中间表已存在的数据，计算出添加、修改、删除执行。
追加外部表，只追加不更新。
var repo = fsql.GetRepository<Topic>(); repo.Delete(new Topic { Id = 1 }); //有重载方法 repo.Delete(Topic[]) var repo2 = fsql.GetRepository<Topic, int>(); //int 是主键类型，相比 repo 对象多了 Delete(int) 方法 repo2.Delete(1); 第一种：基于【对象】级联删除
比如使用过 Include/IncludeMany 查询的对象，可以使用此方法级联删除它们。
var repo = fsql.GetRepository<Group>(); repo.DbContextOptions.EnableCascadeSave = true; //关键设置 repo.Insert(new UserGroup { GroupName = "group01", Users = new List<User> { new User { Username = "admin01", Password = "pwd01", UserExt = new UserExt { Remark = "用户备注01" } }, new User { Username = "admin02", Password = "pwd02", UserExt = new UserExt { Remark = "用户备注02" } }, new User { Username = "admin03", Password = "pwd03", UserExt = new UserExt { Remark = "用户备注03" } }, } }); //级联添加测试数据 //INSERT INTO "usergroup"("groupname") VALUES('group01') RETURNING "id" //INSERT INTO "user"("username", "password", "groupid") VALUES('admin01', 'pwd01', 1), ('admin02', 'pwd02', 1), ('admin03', 'pwd03', 1) RETURNING "id" as "Id", "username" as "Username", "password" as "Password", "groupid" as "GroupId" //INSERT INTO "userext"("userid", "remark") VALUES(3, '用户备注01'), (4, '用户备注02'), (5, '用户备注03') var groups = repo.Select .IncludeMany(a => a.Users, then => then.Include(b => b.UserExt)) .ToList(); repo.Delete(groups); //级联删除，递归向下遍历 group OneToOne/OneToMany/ManyToMany 导航属性 //DELETE FROM "userext" WHERE ("userid" IN (3,4,5)) //DELETE FROM "user" WHERE ("id" IN (3,4,5)) //DELETE FROM "usergroup" WHERE ("id" = 1) 第二种：基于【数据库】级联删除，不依赖数据库外键
根据设置的导航属性，递归删除 OneToOne/OneToMany/ManyToMany 对应数据，并返回已删除的数据。此功能不依赖数据库外键
var repo = fsql.GetRepository<Group>(); var ret = repo.DeleteCascadeByDatabase(a => a.Id == 1); //SELECT a."id", a."username", a."password", a."groupid" FROM "user" a WHERE (a."groupid" = 1) //SELECT a."userid", a."remark" FROM "userext" a WHERE (a."userid" IN (3,4,5)) //DELETE FROM "userext" WHERE ("userid" IN (3,4,5)) //DELETE FROM "user" WHERE ("id" IN (3,4,5)) //DELETE FROM "usergroup" WHERE ("id" = 1) //ret Count = 7 System.Collections.Generic.List<object> // [0] {UserExt} object {UserExt} // [1] {UserExt} object {UserExt} // [2] {UserExt} object {UserExt} // [3] {User} object {User} // [4] {User} object {User} // [5] {User} object {User} // [6] {UserGroup} object {UserGroup} public class Group { [Column(IsIdentity = true)] public int Id { get; set; } public string GroupName { get; set; } [Navigate(nameof(User.GroupId))] public List<User> Users { get; set; } } public class User { [Column(IsIdentity = true)] public int Id { get; set; } public string Username { get; set; } public string Password { get; set; } public int GroupId { get; set; } [Navigate(nameof(Id))] public UserExt UserExt { get; set; } } public class UserExt { [Column(IsPrimary = true)] public int UserId { get; set; } public string Remark { get; set; } [Navigate(nameof(UserId))] public User User { get; set; } } var repo = fsql.GetRepository<Topic>(); repo.InsertOrUpdate(item); 如果内部的状态管理存在数据，则更新。
如果内部的状态管理不存在数据，则查询数据库，判断是否存在。
存在则更新，不存在则插入
缺点：不支持批量操作
提醒：IFreeSql 也定义了 InsertOrUpdate 方法，两者实现机制不同，它利用了数据库特性：
| Database | Features | Database | Features | |
|---|---|---|---|---|
| MySql | on duplicate key update | 达梦 | merge into | |
| PostgreSQL | on conflict do update | 人大金仓 | on conflict do update | |
| SqlServer | merge into | 神通 | merge into | |
| Oracle | merge into | 南大通用 | merge into | |
| Sqlite | replace into | MsAccess | 不支持 | |
| Firebird | merge into |
fsql.InsertOrUpdate<T>() .SetSource(items) //需要操作的数据 //.IfExistsDoNothing() //如果数据存在，啥事也不干（相当于只有不存在数据时才插入） .ExecuteAffrows(); var repo = fsql.GetRepository<BeginEdit01>(); var cts = new[] { new BeginEdit01 { Name = "分类1" }, new BeginEdit01 { Name = "分类1_1" }, new BeginEdit01 { Name = "分类1_2" }, new BeginEdit01 { Name = "分类1_3" }, new BeginEdit01 { Name = "分类2" }, new BeginEdit01 { Name = "分类2_1" }, new BeginEdit01 { Name = "分类2_2" } }.ToList(); repo.Insert(cts); repo.BeginEdit(cts); //开始对 cts 进行编辑 cts.Add(new BeginEdit01 { Name = "分类2_3" }); cts[0].Name = "123123"; cts.RemoveAt(1); var affrows = repo.EndEdit(); //完成编辑 Assert.Equal(3, affrows); class BeginEdit01 { public Guid Id { get; set; } public string Name { get; set; } } 上面的代码 EndEdit 方法执行的时候产生 3 条 SQL 如下：
INSERT INTO "BeginEdit01"("Id", "Name") VALUES('5f26bf07-6ac3-cbe8-00da-7dd74818c3a6', '分类2_3') UPDATE "BeginEdit01" SET "Name" = '123123' WHERE ("Id" = '5f26bf00-6ac3-cbe8-00da-7dd01be76e26') DELETE FROM "BeginEdit01" WHERE ("Id" = '5f26bf00-6ac3-cbe8-00da-7dd11bcf54dc') 场景：winform 加载表数据后，一顿添加、修改、删除操作之后，点击【保存】
提醒：该操作只对变量 cts 有效，不是针对全表对比更新。
var repo = fsql.GetRepository<object>(); repo.AsType(typeof(Topic)); var item = (object)new Topic { Title = "object title" }; repo.Insert(item); 支持参数化、无参数化命令执行，有一些特定的数据库，使用无参数化命令执行效率更高哦，并且调试起来更直观。
var repo = fsql.GetRepository<object>(); repo.DbContextOptions.NoneParameter = true; UnitOfWork 可将多个仓储放在一个单元管理执行，最终通用 Commit 执行所有操作，内部采用了数据库事务。
方法1：随时创建使用
using (var uow = fsql.CreateUnitOfWork()) { var typeRepo = fsql.GetRepository<Type>(); var topicRepo = fsql.GetRepository<Topic>(); typeRepo.UnitOfWork = uow; topicRepo.UnitOfWork = uow; typeRepo.Insert(new Type()); topicRepo.Insert(new Topic()); uow.Orm.Insert(new Topic()).ExecuteAffrows(); //uow.Orm 和 fsql 都是 IFreeSql //uow.Orm CRUD 与 uow 是一个事务 //fsql CRUD 与 uow 不在一个事务 uow.Commit(); } 方法2：使用 AOP + UnitOfWorkManager 实现多种事务传播
本段内容引导，如何在 asp.net core 项目中使用特性(注解) 的方式管理事务。
UnitOfWorkManager 支持六种传播方式(propagation)，意味着跨方法的事务非常方便，并且支持同步异步：
第一步：配置 Startup.cs 注入
public void ConfigureServices(IServiceCollection services) { services.AddSingleton<IFreeSql>(fsql); services.AddScoped<UnitOfWorkManager>(); services.AddFreeRepository(null, typeof(Startup).Assembly); } | UnitOfWorkManager 成员 | 说明 |
|---|---|
| IUnitOfWork Current | 返回当前的工作单元 |
| void Binding(repository) | 将仓储的事务交给它管理 |
| IUnitOfWork Begin(propagation, isolationLevel) | 创建工作单元 |
第二步：定义事务特性
[AttributeUsage(AttributeTargets.Method)] public class TransactionalAttribute : Attribute { /// <summary> /// 事务传播方式 /// </summary> public Propagation Propagation { get; set; } = Propagation.Requierd; /// <summary> /// 事务隔离级别 /// </summary> public IsolationLevel? IsolationLevel { get; set; } } 第三步：引入动态代理库
在 Before 从容器中获取 UnitOfWorkManager，调用它的 var uow = Begin(attr.Propagation, attr.IsolationLevel) 方法
在 After 调用 Before 中的 uow.Commit 或者 Rollback 方法，最后调用 uow.Dispose
提醒：动态代理，一定注意处理好异步 await，否则会出现事务异常的问题
第四步：在 Controller 或者 Service 中使用事务特性
public class TopicService { IBaseRepository<Topic> _repoTopic; IBaseRepository<Detail> _repoDetail; public TopicService(IBaseRepository<Topic> repoTopic, IBaseRepository<Detail> repoDetail) { _repoTopic = repoTopic; _repoDetail = repoDetail; } [Transactional] public virtual void Test1() { //这里 _repoTopic、_repoDetail 所有 CRUD 操作都是一个工作单元 this.Test2(); } [Transactional(Propagation = Propagation.Nested)] public virtual void Test2() //嵌套事务，新的（不使用 Test1 的事务） { //这里 _repoTopic、_repoDetail 所有 CRUD 操作都是一个工作单元 } } 是不是进方法就开事务呢？
不一定是真实事务，有可能是虚的，就是一个假的 unitofwork（不带事务）
也有可能是延用上一次的事务
也有可能是新开事务，具体要看传播模式
示例项目：https://github.com/dotnetcore/FreeSql/tree/master/Examples/aspnetcore_transaction
Autofac 动态代理参考项目：
FreeSql 原生用法、FreeSql.Repository 仓储用法 都提供了 AsTable 方法对分表进行 CRUD 操作，例如：
var repo = fsql.GetRepository<Log>(); repo.AsTable(oldname => $"{oldname}_201903"); //对 Log_201903 表 CRUD repo.Insert(new Log { ... }); 跨库，但是在同一个数据库服务器下，也可以使用 AsTable(oldname => $"db2.dbo.{oldname}")
//跨表查询 var sql = fsql.Select<User>() .AsTable((type, oldname) => "table_1") .AsTable((type, oldname) => "table_2") .ToSql(a => a.Id); //select * from (SELECT a."Id" as1 FROM "table_1" a) ftb //UNION ALL //select * from (SELECT a."Id" as1 FROM "table_2" a) ftb 分表总结：
v3.2.500 按时间自动分表方案：https://github.com/dotnetcore/FreeSql/discussions/1066
FreeSql 他是免费自由的 ORM，也可以说是宝藏 ORM。更多文档请前往 github wiki 查看。
FreeSql 已经步入第四个年头，期待少年的你十年后还能归来在此贴回复，兑现当初吹过十年不变的承诺。
多的不说了，希望民间的开源力量越来越强大。
希望作者的努力能打动到你，请求正在使用的、善良的您能动一动小手指，把文章转发一下，让更多人知道 .NET 有这样一个好用的 ORM 存在。谢谢！！
FreeSql 使用最宽松的开源协议 MIT https://github.com/dotnetcore/FreeSql ，完全可以商用，文档齐全，甚至拿去卖钱也可以。QQ群：4336577(已满)、8578575(在线)、52508226(在线)
