[开源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不见）
廢話開頭
這篇文章是我有史以來編輯最長時間的，歷時 4小時！！！原本我可以利用這 4小時編寫一堆膠水代碼，真心希望善良的您點個贊，謝謝了！！
很久很久沒有寫文章了，上一次還是在元旦發(fā)布 1.0 版本的時候，今年版本規(guī)劃是每月底發(fā)布小版本（年底發(fā)布 2.0），全年的開源工作主要是收集用戶需求增加功能，完善測試，修復(fù) bug。FreeSql 1.0 -> 1.5 相隔半年有哪些新功能？只能說每個功能都能讓我興奮，并且能感受到使用者也一樣興奮（妄想癥）。
迫不及待的人會問，這更新速度也太快了吧，升級會不會有問題？
不了解版本的更新日志，直接升級不是好的習(xí)慣，建議關(guān)注我們的更新日志（github 上有專門的文檔）；
我們的版本開發(fā)原則：在盡量保證兼容的情況下，增加新功能，砍掉少量不合理的功能；
我們的單元測試數(shù)量：4000+，這是我們引以自豪，發(fā)布版本的保障；
2|0入戲準(zhǔn)備
FreeSql 是 .Net ORM，能支持 .NetFramework4.0+、.NetCore、Xamarin、XAUI、Blazor、以及還有說不出來的運行平臺，因為代碼綠色無依賴，支持新平臺非常簡單。目前單元測試數(shù)量：4000+，Nuget下載數(shù)量：123K+，源碼幾乎每天都有提交。值得高興的是 FreeSql 加入了 ncc 開源社區(qū)：https://github.com/dotnetcore/FreeSql，加入組織之后社區(qū)責(zé)任感更大，需要更努力做好品質(zhì)，為開源社區(qū)出一份力。QQ開發(fā)群：4336577
為什么要重復(fù)造輪子？
FreeSql 主要優(yōu)勢在于易用性上，基本是開箱即用，在不同數(shù)據(jù)庫之間切換兼容性比較好。作者花了大量的時間精力在這個項目，肯請您花半小時了解下項目，謝謝。
FreeSql 整體的功能特性如下：
支持 CodeFirst 對比結(jié)構(gòu)變化遷移；
支持 DbFirst 從數(shù)據(jù)庫導(dǎo)入實體類；
支持 豐富的表達式函數(shù)，自定義解析；
支持 批量添加、批量更新、BulkCopy；
支持 導(dǎo)航屬性，貪婪加載、延時加載、級聯(lián)保存；
支持 讀寫分離、分表分庫，租戶設(shè)計；
支持 MySql/SqlServer/PostgreSQL/Oracle/Sqlite/達夢/MsAccess；
1.0 -> 1.5 更新的重要功能如下：
一、UnitOfWorkManager 工作單元管理器，可實現(xiàn) Spring 事務(wù)設(shè)計；
二、IFreeSql.InsertOrUpdate 實現(xiàn)批量保存，執(zhí)行時根據(jù)數(shù)據(jù)庫自動適配執(zhí)行 merge into 或者 on duplicate key update；
三、ISelect.WhereDynamicFilter 方法實現(xiàn)動態(tài)過濾條件（與前端交互）；
四、自動適配表達式解析 yyyyMMdd 常用 c# 日期格式化；
五、IUpdate.SetSourceIgnore 方法實現(xiàn)忽略屬性值為 null 的字段；
六、FreeSql.Provider.Dameng 基于 DmProvider Ado.net 訪問達夢數(shù)據(jù)庫；
七、自動識別 EFCore 常用的實體特性，FreeSql.DbContext 擁有和 EFCore 高相似度的語法，并且支持 90% 相似的 FluentApi；
八、ISelect.ToTreeList 擴展方法查詢數(shù)據(jù)，把配置父子導(dǎo)航屬性的實體加工為樹型 List；
九、BulkCopy 相關(guān)方法提升大批量數(shù)據(jù)插入性能；
十、Sqlite :memrory: 內(nèi)存模式；
FreeSql 使用非常簡單，只需要定義一個 IFreeSql 對象即可：
static IFreeSql fsql = new FreeSql.FreeSqlBuilder().UseConnectionString(FreeSql.DataType.MySql, connectionString).UseAutoSyncStructure(true) //自動同步實體結(jié)構(gòu)到數(shù)據(jù)庫.Build(); //請務(wù)必定義成 Singleton 單例模式?
3|0UnitOfWorkManager 工作單元管理器
public class SongService {BaseRepository<Song> _repo;public SongService(BaseRepository<Song> repo){_repo = repo;}[Transactional]public virtual void Test1(){_repo.Insert(new Song { Title = "卡農(nóng)1" }); //事務(wù)1this.Test2();}[Transactional(Propagation = Propagation.Nested)] //嵌套事務(wù)，新的（不使用 Test1 的事務(wù)）public virtual void Test2(){_repo.Insert(new Song { Title = "卡農(nóng)2" });} }BaseRepository 是 FreeSql.BaseRepository 包實現(xiàn)的通用倉儲類，實際項目中可以繼承它再使用。
Propagation 的模式參考了 Spring 事務(wù)，在以下幾種模式：
Requierd：如果當(dāng)前沒有事務(wù)，就新建一個事務(wù)，如果已存在一個事務(wù)中，加入到這個事務(wù)中，默認(rèn)的選擇。
Supports：支持當(dāng)前事務(wù)，如果沒有當(dāng)前事務(wù)，就以非事務(wù)方法執(zhí)行。
Mandatory：使用當(dāng)前事務(wù)，如果沒有當(dāng)前事務(wù)，就拋出異常。
NotSupported：以非事務(wù)方式執(zhí)行操作，如果當(dāng)前存在事務(wù)，就把當(dāng)前事務(wù)掛起。
Never：以非事務(wù)方式執(zhí)行操作，如果當(dāng)前事務(wù)存在則拋出異常。
Nested：以嵌套事務(wù)方式執(zhí)行。（上面的例子使用的這個）
UnitOfWorkManager 正是干這件事的。避免了每次對數(shù)據(jù)操作都要現(xiàn)獲得 Session 實例來啟動事務(wù)/提交/回滾事務(wù)還有繁瑣的Try/Catch操作。這些也是 AOP（面向切面編程）機制很好的應(yīng)用。一方面使開發(fā)業(yè)務(wù)邏輯更清晰、專業(yè)分工更加容易進行。另一方面就是應(yīng)用 AOP 隔離降低了程序的耦合性使我們可以在不同的應(yīng)用中將各個切面結(jié)合起來使用大大提高了代碼重用度。
使用前準(zhǔn)備第一步：配置 Startup.cs 注入
//Startup.cs public void ConfigureServices(IServiceCollection services) {services.AddSingleton<IFreeSql>(fsql);services.AddScoped<UnitOfWorkManager>();services.AddFreeRepository(null, typeof(Startup).Assembly); }| IUnitOfWork Current | 返回當(dāng)前的工作單元 |
| void Binding(repository) | 將倉儲的事務(wù)交給它管理 |
| IUnitOfWork Begin(propagation, isolationLevel) | 創(chuàng)建工作單元 |
使用前準(zhǔn)備第二步：定義事務(wù)特性
[AttributeUsage(AttributeTargets.Method)] public class TransactionalAttribute : Attribute {/// <summary>/// 事務(wù)傳播方式/// </summary>public Propagation Propagation { get; set; } = Propagation.Requierd;/// <summary>/// 事務(wù)隔離級別/// </summary>public IsolationLevel? IsolationLevel { get; set; } }使用前準(zhǔn)備第三步：引入動態(tài)代理庫
在 Before 從容器中獲取 UnitOfWorkManager，調(diào)用它的 var uow = uowManager.Begin(attr.Propagation, attr.IsolationLevel) 方法
在 After 調(diào)用 Before 中的 uow.Commit 或者 Rollback 方法，最后調(diào)用 uow.Dispose
自問自答：是不是進方法就開事務(wù)呢？
不一定是真實事務(wù)，有可能是虛的，就是一個假的 unitofwork（不帶事務(wù)），也有可能是延用上一次的事務(wù)，也有可能是新開事務(wù)，具體要看傳播模式。
4|0IFreeSql.InsertOrUpdate 批量插入或更新
IFreeSql 定義了 InsertOrUpdate 方法實現(xiàn)批量插入或更新的功能，利用的是數(shù)據(jù)庫特性進行保存，執(zhí)行時根據(jù)數(shù)據(jù)庫自動適配：
| MySql | on duplicate key update |
| PostgreSQL | on conflict do update |
| SqlServer | merge into |
| Oracle | merge into |
| Sqlite | replace into |
| Dameng | merge into |
由于我們前面定義 fsql 變量的類型是 MySql，所以執(zhí)行的語句大概是這樣的：
INSERT INTO `T`(`id`, `name`) VALUES(1, '001'), (2, '002'), (3, '003'), (4, '004') ON DUPLICATE KEY UPDATE `name` = VALUES(`name`)當(dāng)實體類有自增屬性時，批量 InsertOrUpdate 最多可被拆成兩次執(zhí)行，內(nèi)部計算出未設(shè)置自增值、和有設(shè)置自增值的數(shù)據(jù)，分別執(zhí)行 insert into 和 上面講到的 merge into 兩種命令（采用事務(wù)執(zhí)行）。
5|0WhereDynamicFilter 動態(tài)過濾
是否見過這樣的高級查詢功能，WhereDynamicFilter 在后端可以輕松完成這件事情，前端根據(jù) UI 組裝好對應(yīng)的 json 字符串傳給后端就行，如下：
DynamicFilterInfo dyfilter = JsonConvert.DeserializeObject<DynamicFilterInfo>(@" {""Logic"" : ""Or"",""Filters"" :[{""Field"" : ""Code"",""Operator"" : ""NotContains"",""Value"" : ""val1"",""Filters"" :[{""Field"" : ""Name"",""Operator"" : ""NotStartsWith"",""Value"" : ""val2"",}]},{""Field"" : ""Parent.Code"",""Operator"" : ""Eq"",""Value"" : ""val11"",""Filters"" :[{""Field"" : ""Parent.Name"",""Operator"" : ""Contains"",""Value"" : ""val22"",}]}] } "); fsql.Select<VM_District_Parent>().WhereDynamicFilter(dyfilter).ToList(); //SELECT a.""Code"", a.""Name"", a.""ParentCode"", a__Parent.""Code"" as4, a__Parent.""Name"" as5, a__Parent.""ParentCode"" as6 //FROM ""D_District"" a //LEFT JOIN ""D_District"" a__Parent ON a__Parent.""Code"" = a.""ParentCode"" //WHERE?(not((a.""Code"")?LIKE?'%val1%')?AND?not((a.""Name"")?LIKE?'val2%')?OR?a__Parent.""Code""?=?'val11'?AND?(a__Parent.""Name"")?LIKE?'%val22%')支持的操作符：Contains/StartsWith/EndsWith/NotContains/NotStartsWith/NotEndsWith、Equals/Eq/NotEqual、GreaterThan/GreaterThanOrEqual、LessThan/LessThanOrEqual
6|0表達式解析 yyyyMMdd c# 常用日期格式化
不知道大家有沒有這個困擾，在 ORM 表達式使用 DateTime.Now.ToString("yyyyMM") 是件很難轉(zhuǎn)換的事，在我適配的這些數(shù)據(jù)庫中，只有 MsAccess 可以直接翻譯成對應(yīng)的 SQL 執(zhí)行。
這個想法來自另一個 ORM issues，我時不時會去了解其他 ORM 優(yōu)點和缺陷，以便給 FreeSql 做補充。
想法出來之后當(dāng)于，也就是昨天 2020/5/24 奮戰(zhàn)一宿完成的，除了每個數(shù)據(jù)庫進行編碼適配外，更多的時間耗在了單元測試上，目前已全部通過（4000+單元測試不是吹的）。
僅以此功能讓大家感受一下 FreeSql 的認(rèn)真，他不是一些人口中所說的個人項目，謝謝。
var dtn = DateTime.Parse("2020-1-1 0:0:0"); var dts = Enumerable.Range(1, 12).Select(a => dtn.AddMonths(a)).Concat(Enumerable.Range(1, 31).Select(a => dtn.AddDays(a))).Concat(Enumerable.Range(1, 24).Select(a => dtn.AddHours(a))).Concat(Enumerable.Range(1, 60).Select(a => dtn.AddMinutes(a))).Concat(Enumerable.Range(1, 60).Select(a => dtn.AddSeconds(a))); foreach (var dt in dts) {Assert.Equal(dt.ToString("yyyy-MM-dd HH:mm:ss.fff"), fsql.Select<T>().First(a => dt.ToString()));Assert.Equal(dt.ToString("yyyy-MM-dd HH:mm:ss"), fsql.Select<T>().First(a => dt.ToString("yyyy-MM-dd HH:mm:ss")));Assert.Equal(dt.ToString("yyyy-MM-dd HH:mm"), fsql.Select<T>().First(a => dt.ToString("yyyy-MM-dd HH:mm")));Assert.Equal(dt.ToString("yyyy-MM-dd HH"), fsql.Select<T>().First(a => dt.ToString("yyyy-MM-dd HH")));Assert.Equal(dt.ToString("yyyy-MM-dd"), fsql.Select<T>().First(a => dt.ToString("yyyy-MM-dd")));Assert.Equal(dt.ToString("yyyy-MM"), fsql.Select<T>().First(a => dt.ToString("yyyy-MM")));Assert.Equal(dt.ToString("yyyyMMddHHmmss"), fsql.Select<T>().First(a => dt.ToString("yyyyMMddHHmmss")));Assert.Equal(dt.ToString("yyyyMMddHHmm"), fsql.Select<T>().First(a => dt.ToString("yyyyMMddHHmm")));Assert.Equal(dt.ToString("yyyyMMddHH"), fsql.Select<T>().First(a => dt.ToString("yyyyMMddHH")));Assert.Equal(dt.ToString("yyyyMMdd"), fsql.Select<T>().First(a => dt.ToString("yyyyMMdd")));Assert.Equal(dt.ToString("yyyyMM"), fsql.Select<T>().First(a => dt.ToString("yyyyMM")));Assert.Equal(dt.ToString("yyyy"), fsql.Select<T>().First(a => dt.ToString("yyyy")));Assert.Equal(dt.ToString("HH:mm:ss"), fsql.Select<T>().First(a => dt.ToString("HH:mm:ss")));Assert.Equal(dt.ToString("yyyy MM dd HH mm ss yy M d H hh h"), fsql.Select<T>().First(a => dt.ToString("yyyy MM dd HH mm ss yy M d H hh h")));Assert.Equal(dt.ToString("yyyy MM dd HH mm ss yy M d H hh h m s tt t").Replace("上午", "AM").Replace("下午", "PM").Replace("上", "A").Replace("下", "P"), fsql.Select<T>().First(a => dt.ToString("yyyy MM dd HH mm ss yy M d H hh h m s tt t"))); }支持常用 c# 日期格式化，yyyy MM dd HH mm ss yy M d H hh h m s tt t
tt t 為 AM PM
AM PM 這兩個轉(zhuǎn)換不完美，勉強能使用。
7|0IUpdate.SetSourceIgnore 不更新 null 字段
這個功能被用戶提了幾次，每一次都認(rèn)為 FreeSql.Repository 的狀態(tài)對比可以完成這件事。
這一次作者心疼他們了，為什么一定要用某個功能限制住使用者？大家是否經(jīng)常聽誰說 EF框架、MVC框架，框架的定義其實是約束+規(guī)范。
作者不想做這樣的約束，作者更希望盡量提供多一些實用功能讓用戶自己選擇，把項目定義為：功能組件。
fsql.Update<Song>().SetSourceIgnore(item, col => col == null).ExecuteAffrows();第二個參數(shù)是 Func<object, bool> 類型，col 相當(dāng)于屬性的值，上面的代碼更新實體 item 的時候會忽略 == null 的屬性。
8|0Ado.net 訪問達夢數(shù)據(jù)庫
武漢達夢數(shù)據(jù)庫有限公司成立于2000年，為中國電子信息產(chǎn)業(yè)集團(CEC)旗下基礎(chǔ)軟件企業(yè)，專業(yè)從事數(shù)據(jù)庫管理系統(tǒng)的研發(fā)、銷售與服務(wù)，同時可為用戶提供大數(shù)據(jù)平臺架構(gòu)咨詢、數(shù)據(jù)技術(shù)方案規(guī)劃、產(chǎn)品部署與實施等服務(wù)。多年來，達夢公司始終堅持原始創(chuàng)新、獨立研發(fā)，目前已掌握數(shù)據(jù)管理與數(shù)據(jù)分析領(lǐng)域的核心前沿技術(shù)，擁有全部源代碼，具有完全自主知識產(chǎn)權(quán)。
不知道大家沒有聽說過相關(guān)政策，政府推動國產(chǎn)化以后是趨勢，雖然 .NET 不是國產(chǎn)，但是目前無法限制編程語言，當(dāng)下正在對操作系統(tǒng)、數(shù)據(jù)庫強制推進。
我們知道 EFCore for oracle 問題多，并且現(xiàn)在還沒更新到 3.x，在這樣的背景下，一個國產(chǎn)數(shù)據(jù)庫更不能指望誰實現(xiàn)好用的 EFCore。目前看來除了 EFCore for sqlserver 我們沒把握完全占優(yōu)勢，起碼在其他數(shù)據(jù)庫肯定是我們更接地氣。
言歸正傳，達夢數(shù)據(jù)庫其實蠻早就支持了，之前是以 Odbc 的方式實現(xiàn)的，后面根據(jù)使用者的反饋 Odbc 環(huán)境問題比較麻煩，經(jīng)研究決定支持 ado.net 適配，讓使用者更加方便。使用 ado.net 方式連接達夢只需要修改 IFreeSql 創(chuàng)建時候的類型即可，如下：
static IFreeSql fsql = new FreeSql.FreeSqlBuilder().UseConnectionString(FreeSql.DataType.Dameng, connectionString).UseAutoSyncStructure(true) //自動同步實體結(jié)構(gòu)到數(shù)據(jù)庫.Build(); //請務(wù)必定義成 Singleton 單例模式9|0兼容 EFCore 實體特性、FluentApi
EFCore 目前用戶量最多，為了方便一些項目過渡到 FreeSql，我們做了一些 “AI”：
自動識別 EFCore 實體特性：Key/Required/NotMapped/Table/Column
與 EFCore 90% 相似的 FluentApi
fsql.CodeFirst.Entity<Song>(eb => {eb.ToTable("tb_song");eb.Ignore(a => a.Field1);eb.Property(a => a.Title).HasColumnType("varchar(50)").IsRequired();eb.Property(a => a.Url).HasMaxLength(100);eb.Property(a => a.RowVersion).IsRowVersion();eb.Property(a => a.CreateTime).HasDefaultValueSql("current_timestamp");eb.HasKey(a => a.Id);eb.HasIndex(a => new { a.Id, a.Title }).IsUnique().HasName("idx_xxx11");//一對多、多對一eb.HasOne(a => a.Type).HasForeignKey(a => a.TypeId).WithMany(a => a.Songs);//多對多eb.HasMany(a => a.Tags).WithMany(a => a.Songs, typeof(Song_tag)); });fsql.CodeFirst.Entity<SongType>(eb => {eb.HasMany(a => a.Songs).WithOne(a => a.Type).HasForeignKey(a => a.TypeId);eb.HasData(new[]{new SongType{Id = 1,Name = "流行",Songs = new List<Song>(new[]{new Song{ Title = "真的愛你" },new Song{ Title = "愛你一萬年" },})},new SongType{Id = 2,Name = "鄉(xiāng)村",Songs = new List<Song>(new[]{new Song{ Title = "鄉(xiāng)里鄉(xiāng)親" },})},}); });public class SongType {public int Id { get; set; }public string Name { get; set; }public List<Song> Songs { get; set; } } public class Song {[Column(IsIdentity = true)]public int Id { get; set; }public string Title { get; set; }public string Url { get; set; }public DateTime CreateTime { get; set; }public int TypeId { get; set; }public SongType Type { get; set; }public int Field1 { get; set; }public long RowVersion { get; set; } }10|0ISelect.ToTreeList 查詢樹型數(shù)據(jù) List
這是幾個意思？有做過父子關(guān)系的表應(yīng)該知道的，把數(shù)據(jù)查回來了是平面的，需要再用遞歸轉(zhuǎn)化為樹型。考慮到這個功能實用性比較高，所以就集成了進來。來自單元測試的一段代碼：
var repo = fsql.GetRepository<VM_District_Child>(); repo.DbContextOptions.EnableAddOrUpdateNavigateList = true; repo.DbContextOptions.NoneParameter = true; repo.Insert(new VM_District_Child {Code = "100000",Name = "中國",Childs = new List<VM_District_Child>(new[] {new VM_District_Child{Code = "110000",Name = "北京市",Childs = new List<VM_District_Child>(new[] {new VM_District_Child{ Code="110100", Name = "北京市" },new VM_District_Child{ Code="110101", Name = "東城區(qū)" },})}}) }); var t3 = fsql.Select<VM_District_Child>().ToTreeList(); Assert.Single(t3); Assert.Equal("100000", t3[0].Code); Assert.Single(t3[0].Childs); Assert.Equal("110000", t3[0].Childs[0].Code); Assert.Equal(2, t3[0].Childs[0].Childs.Count); Assert.Equal("110100", t3[0].Childs[0].Childs[0].Code); Assert.Equal("110101", t3[0].Childs[0].Childs[1].Code);注意：實體需要配置父子導(dǎo)航屬性
11|0BulkCopy 大批量數(shù)據(jù)
原先 FreeSql 對批量數(shù)據(jù)操作就做得還可以，例如批量數(shù)據(jù)超過數(shù)據(jù)庫某些限制的，會拆分執(zhí)行，性能其實也還行。
本需求也是來自用戶，然后就實現(xiàn)了，實現(xiàn)完了我還專門做了性能測試對比，sqlserver bulkcopy 收益比較大，mysql 收益非常小。
測試結(jié)果(52個字段，18W-50行數(shù)據(jù)，單位ms)：
測試結(jié)果，是在相同操作系統(tǒng)下進行的，并且都有預(yù)熱
ExecuteMySqlBulkCopy 方法在 FreeSql.Provider.MySqlConnector 中實現(xiàn)的
12|0Sqlite :memory: 內(nèi)存模式
了解 EFCore 應(yīng)該知道有一個 inMemory 實現(xiàn)，Sqlite 其實也有內(nèi)存模式，所以在非常棒（忍不住）的 FreeSql.Provider.Sqlite 稍加適配就可以實現(xiàn) inMemory 模式了。
使用 inMemory 模式非常簡單，只需要修改 IFreeSql 創(chuàng)建的類型，以及連接字符串即可：
static IFreeSql fsql = new FreeSql.FreeSqlBuilder().UseConnectionString(FreeSql.DataType.Sqlite, "Data Source=:memory:").UseAutoSyncStructure(true) //自動同步實體結(jié)構(gòu)到數(shù)據(jù)庫.Build(); //請務(wù)必定義成 Singleton 單例模式內(nèi)存模式 + FreeSql CodeFirst 功能，用起來體驗還是不錯的。因為每次都要遷移結(jié)構(gòu)，fsql 釋放數(shù)據(jù)就沒了。
13|0終于寫完了
終于寫完了，這篇文章是我有史以來編輯最長時間的，歷時 4小時！！！原本我可以利用這 4小時編寫一堆膠水代碼，卻非要寫推廣的文章，真心希望正在使用的、善良的您能動一動小手指，把文章轉(zhuǎn)發(fā)一下，讓更多人知道 .NET 有這樣一個好用的 ORM 存在。謝謝了！！
FreeSql 開源協(xié)議 MIT https://github.com/dotnetcore/FreeSql，可以商用，文檔齊全。QQ開發(fā)群：4336577
CSRedisCore 說：FreeSql 的待遇也好太多了。
如果你有好的 ORM 實現(xiàn)想法，歡迎給作者留言討論，謝謝觀看！
總結(jié)
以上是生活随笔為你收集整理的[开源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不见）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： .NET 程序下锐浪报表 (Grid++
- 下一篇： ASP.NET Core on K8s学