.Net orm 开源项目 FreeSql 2.0.0（满意的答卷）

2023-08-21 16:02:58

写在开头

2018年11月头脑发热到今天，一晃已经两年，当初从舒服区走向一个巨大的坑，回头一看后背一凉。

两年时间从无到有，经历数不清的日夜奋斗（有人问花了多长时间投入，答案：全职x2 + 两年无休息）。

今天 FreeSql 已经很强大，感谢第一批、第二批、第N批持续提出建议的朋友，总算给社区交了一个满意答卷。

v2.0.0 是一个稳定的版本，主要体现：

用户 API 已经确定，不会轻易推翻又作调整，坚持五年不变的原则，让使用者真真正正的不再关心 ORM 使用问题；
单元测试覆盖面广，5500+个单元测试，小版本更新升级无须考虑修东墙、补西墙的问题；
经历两年时间的生产考验，nuget下载量已超过25万，平均每日350+；

感叹：有些人说 .Net 陷入 orm 怪圈，动手的没几个，指点*的一堆，.Net orm 真的如他们所讲的简单吗？

项目简介

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

FreeSql 是 .Net ORM，能支持 .NetFramework4.0+、.NetCore、Xamarin、XAUI、Blazor、以及还有说不出来的运行平台，因为代码绿色无依赖，支持新平台非常简单。目前单元测试数量：5400+，Nuget下载数量：260K+，源码几乎每天都有提交。值得高兴的是 FreeSql 加入了 ncc 开源社区：https://github.com/dotnetcore/FreeSql，加入组织之后社区责任感更大，需要更努力做好品质，为开源社区出一份力。

QQ群：4336577(已满)、8578575(在线)、52508226(在线)

为什么要重复造*？

FreeSql 主要优势在于易用性上，基本是开箱即用，在不同数据库之间切换兼容性比较好。作者花了大量的时间精力在这个项目，肯请您花半小时了解下项目，谢谢。FreeSql 整体的功能特性如下：

支持 CodeFirst 对比结构变化迁移；
支持 DbFirst 从数据库导入实体类；
支持丰富的表达式函数，自定义解析；
支持批量添加、批量更新、BulkCopy；
支持导航属性，贪婪加载、延时加载、级联保存；
支持读写分离、分表分库，租户设计；
支持 MySql/SqlServer/PostgreSQL/Oracle/Sqlite/Firebird/达梦/神通/人大金仓/翰高/MsAccess Ado.net 实现包，以及 Odbc 的专门实现包；

5500+个单元测试作为基调，支持10多数数据库，我们提供了通用Odbc理论上支持所有数据库，目前已知有群友使用 FreeSql 操作华为高斯、mycat、tidb 等数据库。

安装时选择对应的数据库包：

dotnet add packages FreeSql.Provider.MySql

CodeFirst

FreeSql 使用 CodeFirst 模式开发，简直不要再简单，只需要如下定义：

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    .UseConnectionString(FreeSql.DataType.MySql, @"Data Source=127.0.0.1;Port=3306;User ID=root;Password=root;Initial Catalog=cccddd_mysqlconnector;Charset=utf8;SslMode=none;Max pool size=10")
    .UseAutoSyncStructure(true) //自动同步实体结构到数据库
    .UseMonitorCommand(cmd => Console.WriteLine(cmd.CommandText + "\r\n")) //打印 SQL
    .Build(); //请务必定义成 Singleton 单例模式

UseAutoSyncStructure(true) 这个设置开启自动迁移功能，啥意思？如下实体类：

class Blog {
    [Column(IsIdentity = true, IsPrimary = true)]
    public int BlogId { get; set; }
    public string Url { get; set; }
    public int Rating { get; set; }
}

fsql 对 Blog 进行 CRUD 时，比如：

fsql.Select<Blog>().First();
fsql.Select<Blog>().First();

会执行 SQL 如下：

CREATE TABLE IF NOT EXISTS `cccddd_mysqlconnector`.`Blog` (  
  `BlogId` INT(11) AUTO_INCREMENT, 
  `Url` VARCHAR(255), 
  `Rating` INT(11) NOT NULL, 
  PRIMARY KEY (`BlogId`)
) Engine=InnoDB;

SELECT a.`BlogId`, a.`Url`, a.`Rating` 
FROM `Blog` a 
limit 0,1

SELECT a.`BlogId`, a.`Url`, a.`Rating` 
FROM `Blog` a 
limit 0,1

程序运行过程中，首次 CRUD 操作实体类会创建表，之后不再执行该操作。

这是表不存在的情况，如果表存在的时候会怎样？会对比更新结构。FreeSql 对比表结构和实体类的差异部分，执行迁移尽量保证不丢数据（无法100%保证，请三思使用在生产环境）

除了自动迁移功能，我们还提供以几个常用 API fsql.CodeFirst 方法：

方法	返回值	参数	说明
GetComparisonDDLStatements	string	Type	将实体类型与数据库对比，返回DDL语句
SyncStructure	bool	Type	同步实体类型到数据库
ConfigEntity	ICodeFirst	Action<TableFluent<T>>	FluentAPI 配置实体的特性
GetTableByEntity	TableInfo	Type	获取类型在ORM内部的元数据

实体特性

.NET ORM 几乎都是通过实体与表进行映射，怎么少得了灵活的特性设置呢。

提示：FreeSql 可以自动识别 EFCore 实体特性 Key/Required/NotMapped/MaxLength/StringLength/DatabaseGenerated/Table/Column

[Table(Name = "topic")]
class Topic {
    [Column(IsPrimary = true, IsIdentity = true, Name = "id")]
    public int Id { get; set; }
}

如上 Name 设置实体类与数据库小写映射，其实还提供统一处理的方法：

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    //..
    UseNameConvert(NameConvertType.ToLower)
    //..
    .Build();

// PascalCaseToUnderscore: BigApple -> Big_Apple
// PascalCaseToUnderscoreWithUpper: BigApple -> BIG_APPLE
// PascalCaseToUnderscoreWithLower: BigApple -> big_apple
// ToUpper: BigApple -> BIGAPPLE
// ToLower: BigApple -> bigapple
// 感谢【晓晨】提供的这个思路和功能

CRUD

FreeSql CRUD 命名习惯遵从 SQL，代码写起来就像写 SQL 一样，如下：

插入数据：fsql.Insert(item).ExecuteAffrows();
更新数据：fsql.Update<T>().Where(..).Set(..).ExecuteAffrows();
删除数据：fsql.Delete<T>().Where(..).ExecuteAffrows();
查询数据：fsql.Select<T>().Where(..).ToList();

Repository

FreeSql.Repository 作为扩展，实现了通用仓储层功能。与其他规范标准一样，仓储层也有相应的规范定义。FreeSql.Repository 参考 abp vnext 接口，定义和实现基础的仓储层（CURD），应该算比较通用的方法吧。仓储可以：

Select/Attach 快照对象，Update 只更新变化的字段；
Insert 插入数据，适配各数据库优化执行 ExecuteAffrows/ExecuteIdentity/ExecuteInserted；
InsertOrUpdate 插入或更新；
SaveMany 方法快速保存导航对象（一对多、多对多）；
UnitOfWork 工作单元设置；

导航属性

微软制造了优秀的语言 c#，利用语言特性可以做一些非常好用的功能，在 ORM 中使用导航属性非常适合。

FreeSql ManyToOne(N对1) 提供了简单的多表 join 查询；
FreeSql OneToMany(1对N) 提供了简单可控的级联查询、级联保存功能；
FreeSql ManyToMany(多对多) 提供了简单的多对多过滤查询、级联查询、级联保存功能；
FreeSql 父子关系提供了常用的 CTE查询、删除、递归功能；

关于导航属性，我们写了一篇专门介绍的文章，可跳转查看：.NET ORM 导航属性【到底】可以解决什么问题？

分表分库

关于分表分库，我们写了一篇专门介绍的文章，可跳转查看：.NET ORM 分表分库【到底】怎么做？

事务

关于事务，我们写了一篇专门介绍的文章，可跳转查看：.NET 数据库事务的各种玩法进化

写在最后

FreeSql 2.0.0 他是免费*的 ORM，也可以说是宝藏 ORM。更多文档请前往 wiki 查看。

下一个五年，期待少年的你还能归来在此贴回复，兑现五年不变的承诺。

多的不说了，希望民间的开源力时越来越强大。

希望作者的努力能打动到你，请求正在使用的、善良的您能动一动小手指，把文章转发一下，让更多人知道 .NET 有这样一个好用的 ORM 存在。谢谢！！

FreeSql 使用最宽松的开源协议 MIT https://github.com/dotnetcore/FreeSql，完全可以商用，文档齐全。QQ群：4336577(已满)、8578575(在线)、52508226(在线)

码农公寓