2018年11月的一天，头脑发热开始了 FreeSql 开源项目之旅已经四年多了。一开始，我从舒适区走到一个巨大的坑。回头看，我的背很凉。四年从无到有，经历了无数的日夜奋战(有人问我花了多长时间答案:全职x2 前两年没有休息，后两年持续投资)。今天 FreeSql 已经很强大了，感谢第一期、第二期、第N期持续提出建议的网友。

FreeSql 现在是一个稳定的版本，主要体现在：

• API 已经确定，不会轻易推翻重作调整，坚持十年不变的原则，让用户真正不再关心 ORM 使用问题；
• 单元测试覆盖面广，6336 单元测试，小版本更新升级不需要考虑修东墙、修西墙的问题；
• 经过四年的生产考验，nuget下载量已超过900K ，平均每日750 ；

感叹：有人说 .Net 陷入 orm 怪圈，动手不多，指点江山一堆，.Net orm 他们说的真的很简单吗？

FreeSql 是 .Net ORM，能支持 .NetFramework4.0 、.NetCore、Xamarin、MAUI、Blazor、还有一个说不出的操作平台，因为代码是绿色的，没有依赖性，支持新平台非常简单。6336 ，Nuget下载数量：900K 。QQ群:4336577(已满)、8578575(在线)、5250826(在线)

温馨提醒：以下内容无商业成分，FreeSql 不打诳语

为什么要重复轮子？

FreeSql 主要优点是易用性，基本开箱即用，不同数据库之间切换兼容性好。作者在这个项目上花了很多时间和精力。请花半个小时了解这个项目。非常感谢。FreeSql 整体功能特点如下：

环境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 对象多线程不安全，不应同时执行多线程。

• fsql.GetRepository 方法返回新的仓储实例
• 不支持同时使用不同线程的同一存储实例

以下是方便测试代码演示的方法1，fsql.GetRepository 创建新的仓储实例

方法二、继承实现；

public class TopicRepository: BaseRepository<Topic, int> { 
             public TopicRepository(IFreeSql fsql) : base(fsql, null, null) { 
        }      //在这里增加 CURD 以外的方法 } 

依赖注入；

public void/span> 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

• SaveMany 仅支持 OneToMany、ManyToMany 导航属性
• 只保存 Topics，不向下递归追朔
• 当 Topics 为 Empty 时，删除 type 存在的 Topics 所有表数据，确认？
• ManyToMany 机制为，完整对比保存中间表，外部表只追加不更新

如：

• 本表 Topic
• 外部表 Tag
• 中间表 TopicTag

功能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);

• 不删除 Topics 子表已存在的数据，确认？
• 当 Topics 属性为 Empty 时，不做任何操作，确认？
• 保存 Topics 的时候，还会保存 Topics[0-…] 的下级集合属性，向下18层，确认？

向下18层的意思，比如【类型】表，下面有集合属性【文章】，【文章】下面有集合属性【评论】。

保存【类型】表对象的时候，他会向下检索出集合属性【文章】，然后如果【文章】被保存的时候，再继续向下检索出集合属性【评论】。一起做 InsertOrUpdate 操作。

3、ManyToMany 完整对比保存中间表，追加外部表

完整对比保存中间表，对比【多对多】中间表已存在的数据，计算出添加、修改、删除执行。

追加外部表，只追加不更新。

• 本表 Topic
• 外部表 Tag
• 中间表 TopicTag

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 方法，两者实现机制不同，它利用了数据库特性：

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)，意味着跨方法的事务非常方便，并且支持同步异步：

• Requierd：如果当前没有事务，就新建一个事务，如果已存在一个事务中，加入到这个事务中，默认的选择。
• Supports：支持当前事务，如果没有当前事务，就以非事务方法执行。
• Mandatory：使用当前事务，如果没有当前事务，就抛出异常。
• NotSupported：以非事务方式执行操作，如果当前存在事务，就把当前事务挂起。
• Never：以非事务方式执行操作，如果当前事务存在则抛出异常。
• Nested：以嵌套事务方式执行。

第一步：配置 Startup.cs 注入

public void ConfigureServices(IServiceCollection services)
{ 
        
    services.AddSingleton<IFreeSql>(fsql);
    services.AddScoped<UnitOfWorkManager>();
    services.AddFreeRepository(null, typeof(Startup).Assembly);
}

第二步：定义事务特性

[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 动态代理参考项目：

• https://github.com/luoyunchong/lin-cms-dotnetcore
• https://github.com/luoyunchong/dotnetcore-examples/tree/master/ORM/FreeSql/OvOv.FreeSql.AutoFac.DynamicProxy
• AOP + FreeSql 跨方法异步事务 https://www.cnblogs.com/igeekfan/p/aop-freesql-autofac.html

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 

分表总结：

• 分表、相同服务器跨库 可以使用 AsTable 进行 CRUD；
• AsTable CodeFirst 会自动创建不存在的分表；
• 不可在分表分库的实体类型中使用《延时加载》；

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(在线)