0. 前言
前幾天FreeSql的作者向我推薦了FreeSql框架,想讓我幫忙寫個文章介紹一下。嗯,想不到我也能帶個貨了。哈哈,開個玩笑~看了下覺得設計的挺有意思的,所以就謝了這篇文章。
簡單介紹一下,FreeSql 是NCC組織的沙盒級專案,是一款功能強大的 ORM 元件,支援 .NET Core、.NET Framework 和 Xamarin。目前 FreeSql 支援以下資料庫:MySQL、PostgreSQL、SqlServer、Oracle、Sqlite、Odbc、微軟 Access 以及國產資料庫達夢。
也就是說也是一個由國內優秀開發者維護的優秀專案,初步看了下功能很齊全。小夥伴們有時間可以取瞅瞅。下圖是我從它GitHub倉庫裡複製過來的。可以看見支援的功能還是相當多的。
關於NCC社群,是.net core的一個開源社群,也是國內最大的.net core開源社群
1. 初步使用
照例,沒安裝就沒有呼叫。所以,在建立專案之後,安裝一下吧:
dotnet add package FreeSql
然後建立一個IFreeSql物件:
public class FreeSqlContext
{
public static IFreeSql FreeSqlConnect { get; } =
new FreeSql.FreeSqlBuilder() .UseConnectionString(FreeSql.DataType.Sqlite, @"Data Source=document.db")
.UseAutoSyncStructure(true) //自動同步實體結構到資料庫
.Build();
}
因為官方要求將IFreeSql物件宣告為單例模式,所以我在這裡使用了靜態屬性。
這種寫法是C#的一種語法糖,只有get表示該屬性是一個只能讀的屬性(與只讀屬性有個微妙的差距),等號後面表示該屬性第一次賦值的內容。
建立一個普通的Model類:
public class Model
{
public int Id { get; set; }
public int StringLength { get; set; }
public string Name { get; set; }
}
1.1 簡單插入
然後試一下插入資料:
var row = FreeSqlContext.FreeSqlConnect.Insert(new Model
{
Name = "測試",
StringLength = 10
}).ExecuteAffrows();
提示如圖內容,需要我們手動安裝一下FreeSql的SQLite驅動,安裝之後:
dotnet add packages FreeSql.Provider.Sqlite
FreeSql針對各種受支援的資料庫都單獨開發了驅動包,統一命名為:
FreeSql.Provider.<資料庫型別>
安裝完成後,重新執行後順利完成執行,順便幫你把資料庫也生成好了(這一點我感覺挺好的),同時生成了一個主鍵為Id的Model表:
create table Model
(
Id INTEGER
primary key,
StringLength INTEGER not null,
Name NVARCHAR(255)
);
1.2 簡單查詢
接下來簡單的查詢一下剛剛插入的資料:
var list = FreeSqlContext.FreeSqlConnect.Queryable<Model>().ToList();
可以發現,查詢使用還是非常方便的。
1.3 簡單更新
FreeSql的更新與其他框架相比略顯複雜,這裡先展示一種更新方式:
list[0].Name = "修改測試";
row = FreeSqlContext.FreeSqlConnect.Update<Model>().SetSource(list[0]).ExecuteAffrows();
先宣告要更新的型別是Model,然後設定更新源。
1.4 簡單刪除
row = FreeSqlContext.FreeSqlConnect.Delete<Model>(new[] { list[0] }).ExecuteAffrows();
刪除之前獲取的資料。
簡單的看,FreeSql設計的增刪改查都是以命令的形式進行的,在實際呼叫ExcuteXXX之前資料並不會儲存到資料庫中。
2. 增刪改查詳解
在上一節中我們簡單的使用了一下增刪改查, 這一節將為大家詳細分析一下FreeSql的增刪改查。
2.1 新增
IInsert<T1> Insert<T1>() where T1 : class;
IInsert<T1> Insert<T1>(T1 source) where T1 : class;
IInsert<T1> Insert<T1>(IEnumerable<T1> source) where T1 : class;
IInsert<T1> Insert<T1>(List<T1> source) where T1 : class;
IInsert<T1> Insert<T1>(T1[] source) where T1 : class;
這是IFreeSql介面裡宣告的Insert方法,通過方法我們可以看到插入單資料插入以及多資料插入,並且返回一個IInsert<T1>的介面。當然也可以不傳入資料直接獲取一個IInsert介面例項。這幾個方法很簡單,我們就不在這多費時間了,然後跳進IInsert裡,看一看裡面有哪些方法吧。
先來這樣一組方法:
IInsert<T1> AppendData(T1 source);
IInsert<T1> AppendData(T1[] source);
IInsert<T1> AppendData(IEnumerable<T1> source);
這些方法可以後續為IInsert繼續新增資料,以便執行更多的插入。
IInsert<T1> IgnoreColumns(string[] columns);
IInsert<T1> IgnoreColumns(Expression<Func<T1, object>> columns);
設定在插入過程中忽略的列,設定之後這些列將不會插入到資料庫中。其中 Expression<Func<T1, object>>
表示一個包含列名屬性的匿名物件。
IInsert<T1> InsertColumns(string[] columns);
IInsert<T1> InsertColumns(Expression<Func<T1, object>> columns);
設定只插入這些列,其他的列將不會被插入。
通過呼叫以下方法將執行插入:
int ExecuteAffrows();// 返回受影響的列
long ExecuteIdentity();// 返回自增主鍵值
這個方法需要實體類的主鍵標記為自增(這部分內容見下一節)。如果啟用了批量插入模式,該值將返回最後一個資料的主鍵值。
List<T1> ExecuteInserted();// 返回插入後的資料
這個方法官方標註只在Postgresql/SqlServer有效果。
這是插入基本內容,相對而言插入比較簡單。
2.2 刪除
這次換個順序,因為刪除的方法在這裡相對簡單一些。FreeSql對於單表的資料刪除相對剋制而謹慎。那麼就讓我們簡單看一下如何進行刪除吧。
IDelete<T1> Delete<T1>() where T1 : class;
設定泛型型別,建立一個刪除器(我給起的名,官方沒給起名,也就是一個IDelete介面例項)。
IDelete<T1> Delete<T1>(object dywhere) where T1 : class;
這個方法很有意思,支援的相當廣泛。
以下是官方給的註釋:
主鍵值 | new[]{主鍵值1,主鍵值2} | TEntity1 | new[]{TEntity1,TEntity2} |new{id=1}
根據實際表現來看,會刪除對應主鍵的資料。如果傳入的是實體的話,會自動分析對應實體的主鍵,然後把這個資料標記為待刪除。
記住這種方式,因為在後續的Update中會用到。
IFreeSql中的刪除都不會立即刪除,都會返回一個IDelete例項,與IInsert一樣需要手動呼叫ExcuteXXX方法。
那麼我們來看一下IDelete裡的方法:
IDelete<T1> Where(Expression<Func<T1, bool>> exp);
IDelete<T1> Where(string sql, object parms = null);
IDelete<T1> Where(T1 item);
IDelete<T1> Where(IEnumerable<T1> items);
簡單看一下方法,可以通過方法和引數就能知道其中含義。
需要注意的是,如果使用exp 做批量刪除的話,只能用實體類的屬性作為條件,不能使用導航屬性。
使用sql語句的話,可以使用引數化寫法如下:Where("id = ?id", new { id = 1 })
,如果有多個條件的話sql裡用and拼接。
IDelete<T1> WhereDynamic(object dywhere, bool not = false);
這裡的dywhere與Delete的dywhere一樣,not 如果設定為true,則表示刪除除此之外的物件。
FreeSql在設計刪除模式時,如果在IFreeSql.Delete中傳入引數,後續繼續呼叫Where或者WhereDynamic的話,兩次是以and 的形式拼接的條件:
list = FreeSqlContext.FreeSqlConnect.Queryable<Model>().ToList();
FreeSqlContext.FreeSqlConnect.Delete<Model>(list[0]).WhereDynamic(list[2]).ExecuteAffrows();
FreeSqlContext.FreeSqlConnect.Delete<Model>(list[0]).Where(t=>t.Id > 10).ExecuteAffrows();
分別生成了如下SQL語句:
DELETE FROM "Model" WHERE ("Id" = 1) AND ("Id" = 11)
----------------------------
DELETE FROM "Model" WHERE ("Id" = 1) AND ("Id" > 10)
額,所以呼叫刪除的時候最好注意一下,因為條件衝突的話,可能資料不會發生任何變化。
執行刪除:
int ExecuteAffrows();//返回被影響的行數
List<T1> ExecuteDeleted();// 返回被刪除的資料,一樣只有 Postgresql/SqlServer 有效果
2.3 更新
IUpdate<T1> Update<T1>() where T1 : class;
IUpdate<T1> Update<T1>(object dywhere) where T1 : class;
同樣,開啟一個更新器(獲取一個IUpdate示例),這裡dywhere與刪除支援的內容是一樣的。不過,有一點不同的是:
row = FreeSqlContext.FreeSqlConnect.Update<Model>(list[0]).ExecuteAffrows();
不會有任何資料發生更改。嗯,這點與Delete完全不一樣。簡單理解一下,在這裡FreeSql只是解析了資料裡的實體,但並沒有從傳入的實體解析出更新SQL語句。
接下來,進入IUpdate:
IUpdate<T1> UpdateColumns(string[] columns);
IUpdate<T1> UpdateColumns(Expression<Func<T1, object>> columns);
IUpdate<T1> IgnoreColumns(Expression<Func<T1, object>> columns);
IUpdate<T1> IgnoreColumns(string[] columns);
設定要更新的列和要忽略的列,兩者互相沖突。
示例:
row = FreeSqlContext.FreeSqlConnect.Update<Model>(list[0]).UpdateColumns(new[] { "Name" }).ExecuteAffrows();
是不是覺得歡天喜地的覺得會更新了,答案很殘酷,沒有。依舊返回0。說到這裡了,FreeSql在更新上,需要額外指定更新的資料來源:
IUpdate<T1> SetSource(T1 source);
IUpdate<T1> SetSource(IEnumerable<T1> source);
也就是,FreeSql會從source解析出需要更新的欄位,然後使用Update/Ignore來設定只更新或忽略哪些列。
最終示例:
row = FreeSqlContext.FreeSqlConnect.Update<Model>(list[0])
.SetSource(list[0]).UpdateColumns(new[] { "Name" }).ExecuteAffrows();
row = FreeSqlContext.FreeSqlConnect.Update<Model>(list[0])
.SetSource(list).UpdateColumns(new[] { "Name" }).ExecuteAffrows();
row = FreeSqlContext.FreeSqlConnect.Update<Model>(new[] { list[0] ,list[1]})
.SetSource(list[0]).UpdateColumns(new[] { "Name" }).ExecuteAffrows();
row = FreeSqlContext.FreeSqlConnect.Update<Model>(new[] { list[0], list[1] })
.SetSource(list).UpdateColumns(new[] { "Name" }).ExecuteAffrows();
然後生成如下SQL:
UPDATE "Model" SET "Name" = @p_0 WHERE ("Id" = 1) AND ("Id" = 1)
--------------------------
UPDATE "Model" SET "Name" = CASE "Id"
WHEN 1 THEN @p_0
WHEN 10 THEN @p_1
WHEN 11 THEN @p_2
WHEN 12 THEN @p_3
WHEN 13 THEN @p_4
WHEN 14 THEN @p_5
WHEN 15 THEN @p_6
WHEN 16 THEN @p_7
WHEN 17 THEN @p_8
WHEN 18 THEN @p_9
WHEN 19 THEN @p_10
WHEN 20 THEN @p_11
WHEN 21 THEN @p_12
WHEN 22 THEN @p_13
WHEN 23 THEN @p_14
WHEN 24 THEN @p_15 END
WHERE ("Id" IN (1,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24)) AND ("Id" = 1)
--------------------
UPDATE "Model" SET "Name" = @p_0 WHERE ("Id" = 1) AND ("Id" = 1 OR "Id" = 10)
--------------------
UPDATE "Model" SET "Name" = CASE "Id"
WHEN 1 THEN @p_0
WHEN 10 THEN @p_1
WHEN 11 THEN @p_2
WHEN 12 THEN @p_3
WHEN 13 THEN @p_4
WHEN 14 THEN @p_5
WHEN 15 THEN @p_6
WHEN 16 THEN @p_7
WHEN 17 THEN @p_8
WHEN 18 THEN @p_9
WHEN 19 THEN @p_10
WHEN 20 THEN @p_11
WHEN 21 THEN @p_12
WHEN 22 THEN @p_13
WHEN 23 THEN @p_14
WHEN 24 THEN @p_15 END
WHERE ("Id" IN (1,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24)) AND ("Id" = 1 OR "Id" = 10)
可以看出,如果在生成IUpdate例項的時候,傳入資料再使用SetSource進行更新會比較詭異。所以SetSource的正常使用方式是,獲取IUpdate例項的時候,不傳dywhere,直接獲取一個空IUpdate。
那麼dywhere該在什麼時候使用呢?
row = FreeSqlContext.FreeSqlConnect.Update<Model>(list[0]).Set(t => t.StringLength + 1).ExecuteAffrows();
通過呼叫Set/SetDto/SetIf三種方法進行更新,當然了這三種方法並不侷限於使用了dywhere引數。
IUpdate<T1> Set<TMember>(Expression<Func<T1, TMember>> exp);
IUpdate<T1> Set<TMember>(Expression<Func<T1, TMember>> column, TMember value);
IUpdate<T1> SetDto(object dto);
IUpdate<T1> SetIf<TMember>(bool condition, Expression<Func<T1, TMember>> exp);
IUpdate<T1> SetIf<TMember>(bool condition, Expression<Func<T1, TMember>> column, TMember value);
其中:
- Expression<Func<T1, TMember>> exp 表示在欄位本身值的基礎上進行操作
- Expression<Func<T1, TMember>> column, TMember value 表示將 column設定 value
- object dto 一個包含要更新屬性和值的匿名類,或者一個字典型別(鍵為要更新的列,值為對應列的值)
- bool condition 表示滿足條件則更新,否則將不進行更新
IUpdate也提供了Where模式:
IUpdate<T1> Where(Expression<Func<T1, bool>> exp);
IUpdate<T1> Where(string sql, object parms = null);
IUpdate<T1> Where(T1 item);
IUpdate<T1> Where(IEnumerable<T1> items);
IUpdate<T1> WhereDynamic(object dywhere, bool not = false);
最終更新應該如下:
FreeSqlContext.FreeSqlConnect.Update<Model>(list[0]).Set(t => t.StringLength + 1).ExecuteAffrows();
FreeSqlContext.FreeSqlConnect.Update<Model>(list[0]).SetDto(new { Name="測試2" }).ExecuteAffrows();
FreeSqlContext.FreeSqlConnect.Update<Model>(list[0]).SetIf(true, t => t.Name + 1).ExecuteAffrows();
// 或者以下模式
FreeSqlContext.FreeSqlConnect.Update<Model>()
.Where(t => true)
.Set(t => t.StringLength + 1)
.ExecuteAffrows();
// 或者
FreeSqlContext.FreeSqlConnect.Update<Model>(1)
.Set(t => t.StringLength + 1)
.ExecuteAffrows();
執行更新:
int ExecuteAffrows();// 返回受影響的行數
List<T1> ExecuteUpdated();// 嗯, 只有 Postgresql/SqlServer 有效果
2.4 查詢
FreeSql的查詢有兩種方式,一種是使用FreeSql的ISelect方法,一種是使用擴充套件出來的Queryable方法,兩者最終返回是一樣的,均返回了一個ISelect例項。
那先來悄悄看一下兩個方法的宣告吧:
ISelect<T1> Select<T1>() where T1 : class;
ISelect<T1> Select<T1>(object dywhere) where T1 : class;
// 擴充套件方法在 FreeSqlGlobalExtensions 類
public static ISelect<T> Queryable<T>(this IFreeSql freesql) where T : class;
其中有一個閃閃放光的 dywhere,與Update/Delete一樣,也是通過傳入的屬性解析到主鍵值獲取對應的資料。
那麼進入ISelect一探究竟吧:
暫且忽略多個泛型支援的方法:
T1 First()
TDto First<TDto>();
TReturn First<TReturn>(Expression<Func<T1, TReturn>> select);
T1 ToOne();
TDto ToOne<TDto>();
TReturn ToOne<TReturn>(Expression<Func<T1, TReturn>> select);
- First和ToOne都是返回第一條資料
- TDto 表示要查詢出來的欄位合集,列名與資料表中一一對應
- Expression<Func<T1, TReturn>> select 型別投影,通過lambda語句建立T1到TReturn之間的關係
返回多個:
List<T1> ToList(bool includeNestedMembers = false);
List<TDto> ToList<TDto>();
List<TReturn> ToList<TReturn>(Expression<Func<T1, TReturn>> select);
- includeNestedMembers : false: 返回 2級 LeftJoin/InnerJoin/RightJoin 物件;true: 返回所有 LeftJoin/InnerJoin/RightJoin的導航資料
其他方法:
long Count();// 返回數目
ISelect<T1> Distinct();//去重
ISelect<T1> Skip(int offset);// 忽略幾個
ISelect<T1> Take(int limit);// 獲取前幾個
ISelect<T1> OrderBy<TMember>(Expression<Func<T1, TMember>> column);// 排序
ISelect<T1> OrderBy<TMember>(bool condition, Expression<Func<T1, TMember>> column);// 排序
ISelect<T1> OrderByDescending<TMember>(Expression<Func<T1, TMember>> column); // 降序
ISelect<T1> OrderByDescending<TMember>(bool condition, Expression<Func<T1, TMember>> column);// 降序
decimal Sum<TMember>(Expression<Func<T1, TMember>> column);// 求和
double Avg<TMember>(Expression<Func<T1, TMember>> column);// 求平均數
設定查詢條件:
ISelect<T1> Where(Expression<Func<T1, bool>> exp);
ISelect<T1> WhereIf(bool condition, Expression<Func<T1, bool>> exp);
ISelect<T1> Where(string sql, object parms = null);
注意與dywhere之間是並列關係。
關於查詢FreeSql做了很多優化,更多內容可以查閱官方文件。到目前為止,這些方法已經可以滿足一個專案的使用了。
3. 總結
FreeSql可以說結合了很多優秀的ORM框架內容,而且針對不同的方式分成了不同的外掛形式,使主幹可以輕裝上陣。
這是官方文件中關於不同使用習慣的介紹。
關於FreeSql的基礎內容就到這裡了,如果對FreeSql有更多的需求的話,可以踴躍吐槽哦~~如果有小夥伴還想看的話,我將會繼續為大家講解的。
至此,2020-5-28 《C# 資料操作系列》暫時 完結(如果後續有其他好的ORM的話,還會繼續更新的)。
更多內容煩請關注我的部落格《高先生小屋》