天天看點
傳回

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）

廢話開頭

這篇文章是我有史以來編輯最長時間的，曆時 4小時！！！原本我可以利用這 4小時編寫一堆膠水代碼，真心希望善良的您點個贊，謝謝了！！

很久很久沒有寫文章了，上一次還是在元旦釋出 1.0 版本的時候，今年版本規劃是每月底釋出小版本（年底釋出 2.0），全年的開源工作主要是收集使用者需求增加功能，完善測試，修複 bug。FreeSql 1.0 -> 1.5 相隔半年有哪些新功能？隻能說每個功能都能讓我興奮，并且能感受到使用者也一樣興奮（妄想症）。

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）

迫不及待的人會問，這更新速度也太快了吧，更新會不會有問題？

  • 不了解版本的更新日志，直接更新不是好的習慣，建議關注我們的更新日志（github 上有專門的文檔）；
  • 我們的版本開發原則：在盡量保證相容的情況下，增加新功能，砍掉少量不合理的功能；
  • 我們的單元測試數量：4000+，這是我們引以自豪，釋出版本的保障；

入戲準備

FreeSql 是 .Net ORM，能支援 .NetFramework4.0+、.NetCore、Xamarin、XAUI、Blazor、以及還有說不出來的運作平台，因為代碼綠色無依賴，支援新平台非常簡單。目前單元測試數量：4000+，Nuget下載下傳數量：123K+，源碼幾乎每天都有送出。值得高興的是 FreeSql 加入了 ncc 開源社群：https://github.com/dotnetcore/FreeSql，加入組織之後社群責任感更大，需要更努力做好品質，為開源社群出一份力。

QQ群：4336577(已滿)、8578575(線上)、52508226(線上)

為什麼要重複造輪子？

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）
FreeSql 主要優勢在于易用性上，基本是開箱即用，在不同資料庫之間切換相容性比較好。作者花了大量的時間精力在這個項目，肯請您花半小時了解下項目，謝謝。

FreeSql 整體的功能特性如下：

  • 支援 CodeFirst 對比結構變化遷移；
  • 支援 DbFirst 從資料庫導入實體類；
  • 支援 豐富的表達式函數，自定義解析；
  • 支援 批量添加、批量更新、BulkCopy；
  • 支援 導航屬性，貪婪加載、延時加載、級聯儲存；
  • 支援 讀寫分離、分表分庫，租戶設計；
  • 支援 MySql/SqlServer/PostgreSQL/Oracle/Sqlite/達夢/翰高/MsAccess；

1.0 -> 1.5 更新的重要功能如下：

一、UnitOfWorkManager 工作單元管理器，可實作 Spring 事務設計；

二、IFreeSql.InsertOrUpdate 實作批量儲存，執行時根據資料庫自動适配執行 merge into 或者 on duplicate key update；

三、ISelect.WhereDynamicFilter 方法實作動态過濾條件（與前端互動）；

四、自動适配表達式解析 yyyyMMdd 常用 c# 日期格式化；

五、IUpdate.SetSourceIgnore 方法實作忽略屬性值為 null 的字段；

六、FreeSql.Provider.Dameng 基于 DmProvider Ado.net 通路達夢資料庫；

七、自動識别 EFCore 常用的實體特性，FreeSql.DbContext 擁有和 EFCore 高相似度的文法，并且支援 90% 相似的 FluentApi；

八、ISelect.ToTreeList 擴充方法查詢資料，把配置父子導航屬性的實體加工為樹型 List；

九、BulkCopy 相關方法提升大批量資料插入性能；

十、Sqlite :memrory: 記憶體模式；

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）

FreeSql 使用非常簡單，隻需要定義一個 IFreeSql 對象即可：

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    .UseConnectionString(FreeSql.DataType.MySql, connectionString)
    .UseAutoSyncStructure(true) //自動同步實體結構到資料庫
    .Build(); //請務必定義成 Singleton 單例模式

UnitOfWorkManager 工作單元管理器 

public class SongService
{
    BaseRepository<Song> _repo;

    public SongService(BaseRepository<Song> repo)
    {
        _repo = repo;
    }

    [Transactional]
    public virtual void Test1()
    {
        _repo.Insert(new Song { Title = "卡農1" }); //事務1
        this.Test2();
    }

    [Transactional(Propagation = Propagation.Nested)] //嵌套事務，新的（不使用 Test1 的事務）
    public virtual void Test2()
    {
        _repo.Insert(new Song { Title = "卡農2" });
    }
}

BaseRepository 是 FreeSql.BaseRepository 包實作的通用倉儲類，實際項目中可以繼承它再使用。

Propagation 的模式參考了 Spring 事務，在以下幾種模式：

  • Requierd：如果目前沒有事務，就建立一個事務，如果已存在一個事務中，加入到這個事務中，預設的選擇。
  • Supports：支援目前事務，如果沒有目前事務，就以非事務方法執行。
  • Mandatory：使用目前事務，如果沒有目前事務，就抛出異常。
  • NotSupported：以非事務方式執行操作，如果目前存在事務，就把目前事務挂起。
  • Never：以非事務方式執行操作，如果目前事務存在則抛出異常。
  • Nested：以嵌套事務方式執行。（上面的例子使用的這個）

UnitOfWorkManager 正是幹這件事的。避免了每次對資料操作都要現獲得 Session 執行個體來啟動事務/送出/復原事務還有繁瑣的Try/Catch操作。這些也是 AOP（面向切面程式設計）機制很好的應用。一方面使開發業務邏輯更清晰、專業分工更加容易進行。另一方面就是應用 AOP 隔離降低了程式的耦合性使我們可以在不同的應用中将各個切面結合起來使用大大提高了代碼重用度。

使用前準備第一步：配置 Startup.cs 注入

//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 = uowManager.Begin(attr.Propagation, attr.IsolationLevel) 方法

在 After 調用 Before 中的 uow.Commit 或者 Rollback 方法，最後調用 uow.Dispose

自問自答：是不是進方法就開事務呢？

不一定是真實事務，有可能是虛的，就是一個假的 unitofwork（不帶事務），也有可能是延用上一次的事務，也有可能是新開事務，具體要看傳播模式。

IFreeSql.InsertOrUpdate 批量插入或更新

IFreeSql 定義了 InsertOrUpdate 方法實作批量插入或更新的功能，利用的是資料庫特性進行儲存，執行時根據資料庫自動适配：

Database Features
MySql on duplicate key update
PostgreSQL on conflict do update
SqlServer merge into
Oracle
Sqlite replace into
Dameng 
fsql.InsertOrUpdate<T>()
  .SetSource(items) //需要操作的資料
  .ExecuteAffrows();

由于我們前面定義 fsql 變量的類型是 MySql，是以執行的語句大概是這樣的：

INSERT INTO `T`(`id`, `name`) VALUES(1, '001'), (2, '002'), (3, '003'), (4, '004')
ON DUPLICATE KEY UPDATE
`name` = VALUES(`name`)

當實體類有自增屬性時，批量 InsertOrUpdate 最多可被拆成兩次執行，内部計算出未設定自增值、和有設定自增值的資料，分别執行 insert into 和 上面講到的 merge into 兩種指令（采用事務執行）。

WhereDynamicFilter 動态過濾

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）

是否見過這樣的進階查詢功能，WhereDynamicFilter 在後端可以輕松完成這件事情，前端根據 UI 組裝好對應的 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

表達式解析 yyyyMMdd c# 常用日期格式化

不知道大家有沒有這個困擾，在 ORM 表達式使用 DateTime.Now.ToString("yyyyMM") 是件很難轉換的事，在我适配的這些資料庫中，隻有 MsAccess 可以直接翻譯成對應的 SQL 執行。

這個想法來自另一個 ORM issues，我時不時會去了解其他 ORM 優點和缺陷，以便給 FreeSql 做補充。

想法出來之後當于，也就是昨天 2020/5/24 奮戰一宿完成的，除了每個資料庫進行編碼适配外，更多的時間耗在了單元測試上，目前已全部通過（4000+單元測試不是吹的）。

僅以此功能讓大家感受一下 FreeSql 的認真，他不是一些人口中所說的個人項目，謝謝。
[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）
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 這兩個轉換不完美，勉強能使用。

IUpdate.SetSourceIgnore 不更新 null 字段

這個功能被使用者提了幾次，每一次都認為 FreeSql.Repository 的狀态對比可以完成這件事。

這一次作者心疼他們了，為什麼一定要用某個功能限制住使用者？大家是否經常聽誰說 EF架構、MVC架構，架構的定義其實是限制+規範。

作者不想做這樣的限制，作者更希望盡量提供多一些實用功能讓使用者自己選擇，把項目定義為：功能元件。

fsql.Update<Song>()
  .SetSourceIgnore(item, col => col == null)
  .ExecuteAffrows();

第二個參數是 Func<object, bool> 類型，col 相當于屬性的值，上面的代碼更新實體 item 的時候會忽略 == null 的屬性。

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）

Ado.net 通路達夢資料庫

武漢達夢資料庫有限公司成立于2000年，為中國電子資訊産業集團(CEC)旗下基礎軟體企業，專業從事資料庫管理系統的研發、銷售與服務，同時可為使用者提供大資料平台架構咨詢、資料技術方案規劃、産品部署與實施等服務。多年來，達夢公司始終堅持原始創新、獨立研發，目前已掌握資料管理與資料分析領域的核心前沿技術，擁有全部源代碼，具有完全自主知識産權。

不知道大家沒有聽說過相關政策，政府推動國産化以後是趨勢，雖然 .NET 不是國産，但是目前無法限制程式設計語言，當下正在對作業系統、資料庫強制推進。

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）

我們知道 EFCore for oracle 問題多，并且現在還沒更新到 3.x，在這樣的背景下，一個國産資料庫更不能指望誰實作好用的 EFCore。目前看來除了 EFCore for sqlserver 我們沒把握完全占優勢，起碼在其他資料庫肯定是我們更接地氣。

言歸正傳，達夢資料庫其實蠻早就支援了，之前是以 Odbc 的方式實作的，後面根據使用者的回報 Odbc 環境問題比較麻煩，經研究決定支援 ado.net 适配，讓使用者更加友善。使用 ado.net 方式連接配接達夢隻需要修改 IFreeSql 建立時候的類型即可，如下：

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    .UseConnectionString(FreeSql.DataType.Dameng, connectionString)
    .UseAutoSyncStructure(true) //自動同步實體結構到資料庫
    .Build(); //請務必定義成 Singleton 單例模式

相容 EFCore 實體特性、FluentApi

EFCore 目前使用者量最多，為了友善一些項目過渡到 FreeSql，我們做了一些 “AI”：

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）
  • 自動識别 EFCore 實體特性：Key/Required/NotMapped/Table/Column 
[Table("table01")] //這個其實是 EFCore 的特性
class MyTable
{
    [Key]
    public int Id { get; set; }
}
  • 與 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 = "鄉村",
            Songs = new List<Song>(new[]
            {
                new Song{ Title = "鄉裡鄉親" },
            })
        },
    });
});

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; }
}

ISelect.ToTreeList 查詢樹型資料 List

這是幾個意思？有做過父子關系的表應該知道的，把資料查回來了是平面的，需要再用遞歸轉化為樹型。考慮到這個功能實用性比較高，是以就內建了進來。來自單元測試的一段代碼：

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 = "東城區" },
            })
        }
    })
});
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);

注意：實體需要配置父子導航屬性

BulkCopy 大批量資料

原先 FreeSql 對批量資料操作就做得還可以，例如批量資料超過資料庫某些限制的，會拆分執行，性能其實也還行。

本需求也是來自使用者，然後就實作了，實作完了我還專門做了性能測試對比，sqlserver bulkcopy 收益比較大，mysql 收益非常小。

測試結果(52個字段，18W-50行資料，機關ms)：

18W 1W 5K 500 50
MySql 5.5 ExecuteAffrows 38,481 2,234 1,136 167 30
MySql 5.5 ExecuteMySqlBulkCopy 28,405 1,142 657 592 22
SqlServer Express ExecuteAffrows 402,355 24,847 11,465 915 88
SqlServer Express ExecuteSqlBulkCopy 21,065 578 326 79 48
PostgreSQL 10 ExecuteAffrows 46,756 3,294 2,269 209 37
PostgreSQL 10 ExecutePgCopy 10,090 583 337 61 25
Oracle XE ExecuteAffrows - 10,648 200
Sqlite ExecuteAffrows 28,554 1,149 701 91 35
Oracle 插入性能不用懷疑，可能安裝學生版限制較大

測試結果(10個字段，18W-50行資料，機關ms)：
11,171 866 366 34
6,504 399 257 100 16
47,204 2,275 1,108 123
4,248 127 71 14 10
9,786 568 336 6
4,081 93 12 2
731 33
4,524 246 137 19 11
測試結果，是在相同作業系統下進行的，并且都有預熱
ExecuteMySqlBulkCopy 方法在 FreeSql.Provider.MySqlConnector 中實作的

Sqlite :memory: 記憶體模式

了解 EFCore 應該知道有一個 inMemory 實作，Sqlite 其實也有記憶體模式，是以在非常棒（忍不住）的 FreeSql.Provider.Sqlite 稍加适配就可以實作 inMemory 模式了。

使用 inMemory 模式非常簡單，隻需要修改 IFreeSql 建立的類型，以及連接配接字元串即可：

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    .UseConnectionString(FreeSql.DataType.Sqlite, "Data Source=:memory:")
    .UseAutoSyncStructure(true) //自動同步實體結構到資料庫
    .Build(); //請務必定義成 Singleton 單例模式

記憶體模式 + FreeSql CodeFirst 功能，用起來體驗還是不錯的。因為每次都要遷移結構，fsql 釋放資料就沒了。

終于寫完了

[開源] .Net orm FreeSql 1.5.0 最新版本（番号：好久不見）

終于寫完了，這篇文章是我有史以來編輯最長時間的，曆時 4小時！！！原本我可以利用這 4小時編寫一堆膠水代碼，卻非要寫推廣的文章，真心希望正在使用的、善良的您能動一動小手指，把文章轉發一下，讓更多人知道 .NET 有這樣一個好用的 ORM 存在。謝謝了！！

FreeSql 開源協定 MIT https://github.com/dotnetcore/FreeSql，可以商用，文檔齊全。QQ開發群：4336577(已滿)、8578575(線上)、52508226(線上)

CSRedisCore 說：FreeSql 的待遇也好太多了。

如果你有好的 ORM 實作想法，歡迎給作者留言讨論，謝謝觀看！

ORM FreeSql .net bulkcopy
上一篇: FreeSql 新功能介紹：貪婪加載五種方法
下一篇: [開源] FreeSql.AdminLTE 功能更新

繼續閱讀