# 寫在開頭 2018年11月頭腦發熱到今天，一晃已經兩年，當初從舒服區走向一個巨大的坑，回頭一看後背一涼。 兩年時間從無到有，經歷數不清的日夜奮鬥（有人問花了多長時間投入，答案：全職x2 + 兩年無休息）。 今天 FreeSql 已經很強大，感謝第一批、第二批、第N批持續提出建議的朋友，總算給社群交了一個滿意答卷。 v2.0.0 是一個穩定的版本，主要體現： - 使用者 API 已經確定，不會輕易推翻又作調整，堅持五年不變的原則，讓使用者真真正正的不再關心 ORM 使用問題； - 單元測試覆蓋面廣，5500+個單元測試，小版本更新升級無須考慮修東牆、補西牆的問題； - 經歷兩年時間的生產考驗，nuget下載量已超過25萬，平均每日350+； 感嘆：有些人說 .Net 陷入 orm 怪圈，動手的沒幾個，指點江山的一堆，.Net orm 真的如他們所講的簡單嗎？ # 專案簡介 > 溫馨提醒：以下內容無商吹成份，FreeSql 不打誑語 > 溫馨提醒：以下內容無商吹成份，FreeSql 不打誑語 > 溫馨提醒：以下內容無商吹成份，FreeSql 不打誑語 FreeSql 是 .Net ORM，能支援 .NetFramework4.0+、.NetCore、Xamarin、MAUI、Blazor、以及還有說不出來的執行平臺，因為程式碼綠色無依賴，支援新平臺非常簡單。目前單元測試數量：5400+，Nuget下載數量：260K+，原始碼幾乎每天都有提交。值得高興的是 FreeSql 加入了 ncc 開源社群：[https://github.com/dotnetcore/FreeSql](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 等資料庫。 安裝時選擇對應的資料庫包： ```bash dotnet add packages FreeSql.Provider.MySql ``` # CodeFirst FreeSql 使用 CodeFirst 模式開發，簡直不要再簡單，只需要如下定義： ```csharp 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) 這個設定開啟自動遷移功能，啥意思？如下實體類： ```c# 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 時，比如： ```c# fsql.Select().First(); fsql.Select().First(); ``` 會執行 SQL 如下： ```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\\> | FluentAPI 配置實體的特性 | | GetTableByEntity | TableInfo | Type | 獲取型別在ORM內部的元資料 | # 實體特性 .NET ORM 幾乎都是通過實體與表進行對映，怎麼少得了靈活的特性設定呢。 > 提示：FreeSql 可以自動識別 EFCore 實體特性 Key/Required/NotMapped/MaxLength/StringLength/DatabaseGenerated/Table/Column ```csharp [Table(Name = "topic")] class Topic { [Column(IsPrimary = true, IsIdentity = true, Name = "id")] public int Id { get; set; } } ``` 如上 Name 設定實體類與資料庫小寫對映，其實還提供統一處理的方法： ```c# 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\().Where(..).Set(..).ExecuteAffrows(); - 刪除資料：fsql.Delete\().Where(..).ExecuteAffrows(); - 查詢資料：fsql.Select\().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 導航屬性【到底】可以解決什麼問題？](https://www.cnblogs.com/kellynic/p/13575053.html) # 分表分庫 關於分表分庫，我們寫了一篇專門介紹的文章，可跳轉檢視：[.NET ORM 分表分庫【到底】怎麼做？](https://www.cnblogs.com/kellynic/p/13584095.html) # 事務 關於事務，我們寫了一篇專門介紹的文章，可跳轉檢視：[.NET 資料庫事務的各種玩法進化](https://www.cnblogs.com/kellynic/p/13551855.html) # 寫在最後 FreeSql 2.0.0 他是免費自由的 ORM，也可以說是寶藏 ORM。更多文件請前往 [wiki](https://github.com/dotnetcore/FreeSql/wiki) 檢視。 下一個五年，期待少年的你還能歸來在此貼回覆，兌現五年不變的承諾。 多的不說了，希望民間的開源力時越來越強大。 希望作者的努力能打動到你，請求正在使用的、善良的您能動一動小手指，把文章轉發一下，讓更多人知道 .NET 有這樣一個好用的 ORM 存在。謝謝！！ FreeSql 使用最寬鬆的開源協議 MIT [https://github.com/dotnetcore/FreeSql](https://github.com/dotnetcore/FreeSql)，完全可以商用，文件齊全。QQ群：4336577(已滿)、8578575(線上)、52508226(線上)