C# 數據操作系列 - 19 FreeSql 入坑介紹

前言
前幾天FreeSql的作者向我推薦了FreeSql框架，想讓我幫忙寫個文章介紹一下。嗯，想不到我也能帶個貨了。哈哈，開個玩笑～看了下覺得設計的挺有意思的，所以就謝了這篇文章。

簡單介紹一下，FreeSql 是NCC組織的沙盒級項目，是一款功能強大的 ORM 組件，支持 .NET Core、.NET Framework 和 Xamarin。目前 FreeSql 支持以下數據庫：MySQL、PostgreSQL、SqlServer、Oracle、Sqlite、Odbc、微軟 Access 以及國產數據庫達夢。

也就是說也是一個由國內優秀開發者維護的優秀項目，初步看了下功能很齊全。小夥伴們有時間可以取瞅瞅。下圖是我從它GitHub倉庫裏複製過來的。可以看見支持的功能還是相當多的。

關於NCC社區，是.net core的一個開源社區，也是國內最大的.net core開源社區

初步使用
照例，沒安裝就沒有調用。所以，在創建項目之後，安裝一下吧：

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().ToList();
可以發現，查詢使用還是非常方便的。

1.3 簡單更新
FreeSql的更新與其他框架相比略顯複雜，這裏先展示一種更新方式：

list[0].Name = "修改測試";
row = FreeSqlContext.FreeSqlConnect.Update().SetSource(list[0]).ExecuteAffrows();
先聲明要更新的類型是Model，然後設置更新源。

1.4 簡單刪除
row = FreeSqlContext.FreeSqlConnect.Delete(new[] { list[0] }).ExecuteAffrows();
刪除之前獲取的數據。

簡單的看，FreeSql設計的增刪改查都是以命令的形式進行的，在實際調用ExcuteXXX之前數據並不會保存到數據庫中。

增刪改查詳解
在上一節中我們簡單的使用了一下增刪改查，這一節將爲大家詳細分析一下FreeSql的增刪改查。

2.1 新增
IInsert Insert() where T1 : class;
IInsert Insert(T1 source) where T1 : class;
IInsert Insert(IEnumerable source) where T1 : class;
IInsert Insert(List source) where T1 : class;
IInsert Insert(T1[] source) where T1 : class;
這是IFreeSql接口裏聲明的Insert方法，通過方法我們可以看到插入單數據插入以及多數據插入，並且返回一個IInsert的接口。當然也可以不傳入數據直接獲取一個IInsert接口實例。這幾個方法很簡單，我們就不在這多費時間了，然後跳進IInsert裏，看一看裏面有哪些方法吧。

先來這樣一組方法：

IInsert AppendData(T1 source);
IInsert AppendData(T1[] source);
IInsert AppendData(IEnumerable source);
這些方法可以後續爲IInsert繼續添加數據，以便執行更多的插入。

IInsert IgnoreColumns(string[] columns);
IInsert IgnoreColumns(Expression> columns);
設置在插入過程中忽略的列，設置之後這些列將不會插入到數據庫中。其中 Expression>表示一個包含列名屬性的匿名對象。

IInsert InsertColumns(string[] columns);
IInsert InsertColumns(Expression> columns);
設置只插入這些列，其他的列將不會被插入。

通過調用以下方法將執行插入：

int ExecuteAffrows();// 返回受影響的列
long ExecuteIdentity();// 返回自增主鍵值
這個方法需要實體類的主鍵標記爲自增（這部分內容見下一節）。如果啓用了批量插入模式，該值將返回最後一個數據的主鍵值。

List ExecuteInserted();// 返回插入後的數據
這個方法官方標註只在Postgresql/SqlServer有效果。

這是插入基本內容，相對而言插入比較簡單。

2.2 刪除
這次換個順序，因爲刪除的方法在這裏相對簡單一些。FreeSql對於單表的數據刪除相對剋制而謹慎。那麼就讓我們簡單看一下如何進行刪除吧。

IDelete Delete() where T1 : class;
設置泛型類型，創建一個刪除器（我給起的名，官方沒給起名，也就是一個IDelete接口實例）。

IDelete Delete(object dywhere) where T1 : class;
這個方法很有意思，支持的相當廣泛。

以下是官方給的註釋：

主鍵值 | new[]{主鍵值1,主鍵值2} | TEntity1 | new[]{TEntity1,TEntity2} |new{id=1}
根據實際表現來看，會刪除對應主鍵的數據。如果傳入的是實體的話，會自動分析對應實體的主鍵，然後把這個數據標記爲待刪除。

記住這種方式，因爲在後續的Update中會用到。

IFreeSql中的刪除都不會立即刪除，都會返回一個IDelete實例，與IInsert一樣需要手動調用ExcuteXXX方法。

那麼我們來看一下IDelete裏的方法：

IDelete Where(Expression> exp);
IDelete Where(string sql, object parms = null);
IDelete Where(T1 item);
IDelete Where(IEnumerable items);
簡單看一下方法，可以通過方法和參數就能知道其中含義。

需要注意的是，如果使用exp 做批量刪除的話，只能用實體類的屬性作爲條件，不能使用導航屬性。

使用sql語句的話，可以使用參數化寫法如下：Where("id = ?id", new { id = 1 })，如果有多個條件的話sql裏用and拼接。

IDelete WhereDynamic(object dywhere, bool not = false);
這裏的dywhere與Delete的dywhere一樣，not 如果設置爲true，則表示刪除除此之外的對象。

FreeSql在設計刪除模式時，如果在IFreeSql.Delete中傳入參數，後續繼續調用Where或者WhereDynamic的話，兩次是以and 的形式拼接的條件：

list = FreeSqlContext.FreeSqlConnect.Queryable().ToList();
FreeSqlContext.FreeSqlConnect.Delete(list[0]).WhereDynamic(list[2]).ExecuteAffrows();
FreeSqlContext.FreeSqlConnect.Delete(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 ExecuteDeleted();// 返回被刪除的數據，一樣只有 Postgresql/SqlServer 有效果
2.3 更新
IUpdate Update() where T1 : class;
IUpdate Update(object dywhere) where T1 : class;
同樣，開啓一個更新器（獲取一個IUpdate示例），這裏dywhere與刪除支持的內容是一樣的。不過，有一點不同的是：

row = FreeSqlContext.FreeSqlConnect.Update(list[0]).ExecuteAffrows();
不會有任何數據發生更改。嗯，這點與Delete完全不一樣。簡單理解一下，在這裏FreeSql只是解析了數據裏的實體，但並沒有從傳入的實體解析出更新SQL語句。

接下來，進入IUpdate：

IUpdate UpdateColumns(string[] columns);
IUpdate UpdateColumns(Expression> columns);
IUpdate IgnoreColumns(Expression> columns);
IUpdate IgnoreColumns(string[] columns);
設置要更新的列和要忽略的列，兩者互相沖突。

示例：

row = FreeSqlContext.FreeSqlConnect.Update(list[0]).UpdateColumns(new[] { "Name" }).ExecuteAffrows();
是不是覺得歡天喜地的覺得會更新了，答案很殘酷，沒有。依舊返回0。說到這裏了，FreeSql在更新上，需要額外指定更新的數據來源：

IUpdate SetSource(T1 source);
IUpdate SetSource(IEnumerable source);
也就是，FreeSql會從source解析出需要更新的字段，然後使用Update/Ignore來設置只更新或忽略哪些列。

最終示例：

row = FreeSqlContext.FreeSqlConnect.Update(list[0])

.SetSource(list[0]).UpdateColumns(new[] { "Name" }).ExecuteAffrows();

row = FreeSqlContext.FreeSqlConnect.Update(list[0])

.SetSource(list).UpdateColumns(new[] { "Name" }).ExecuteAffrows();

row = FreeSqlContext.FreeSqlConnect.Update(new[] { list[0] ,list[1]})

.SetSource(list[0]).UpdateColumns(new[] { "Name" }).ExecuteAffrows();

row = FreeSqlContext.FreeSqlConnect.Update(new[] { list[0], list[1] })

.SetSource(list).UpdateColumns(new[] { "Name" }).ExecuteAffrows();

然後生成如下SQL：

UPDATE "Model" SET "Name" = @p_0 WHERE ("Id" = 1) AND ("Id" = 1)

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(list[0]).Set(t => t.StringLength + 1).ExecuteAffrows();
通過調用Set/SetDto/SetIf三種方法進行更新，當然了這三種方法並不侷限於使用了dywhere參數。

IUpdate Set(Expression> exp);
IUpdate Set(Expression> column, TMember value);
IUpdate SetDto(object dto);
IUpdate SetIf(bool condition, Expression> exp);
IUpdate SetIf(bool condition, Expression> column, TMember value);
其中：

Expression> exp 表示在字段本身值的基礎上進行操作
Expression> column, TMember value 表示將 column設置 value
object dto 一個包含要更新屬性和值的匿名類，或者一個字典類型（鍵爲要更新的列，值爲對應列的值）
bool condition 表示滿足條件則更新，否則將不進行更新
IUpdate也提供了Where模式：

IUpdate Where(Expression> exp);
IUpdate Where(string sql, object parms = null);
IUpdate Where(T1 item);
IUpdate Where(IEnumerable items);
IUpdate WhereDynamic(object dywhere, bool not = false);
最終更新應該如下：

FreeSqlContext.FreeSqlConnect.Update(list[0]).Set(t => t.StringLength + 1).ExecuteAffrows();
FreeSqlContext.FreeSqlConnect.Update(list[0]).SetDto(new { Name="測試2" }).ExecuteAffrows();
FreeSqlContext.FreeSqlConnect.Update(list[0]).SetIf(true, t => t.Name + 1).ExecuteAffrows();
// 或者以下模式
FreeSqlContext.FreeSqlConnect.Update()

            .Where(t => true)
            .Set(t => t.StringLength + 1)
            .ExecuteAffrows();

// 或者
FreeSqlContext.FreeSqlConnect.Update(1)

            .Set(t => t.StringLength + 1)
            .ExecuteAffrows();

執行更新：

int ExecuteAffrows();// 返回受影響的行數
List ExecuteUpdated();// 嗯，只有 Postgresql/SqlServer 有效果
2.4 查詢
FreeSql的查詢有兩種方式，一種是使用FreeSql的ISelect方法，一種是使用擴展出來的Queryable方法，兩者最終返回是一樣的，均返回了一個ISelect實例。

那先來悄悄看一下兩個方法的聲明吧：

ISelect Select() where T1 : class;
ISelect Select(object dywhere) where T1 : class;
// 擴展方法在 FreeSqlGlobalExtensions 類
public static ISelect Queryable(this IFreeSql freesql) where T : class;
其中有一個閃閃放光的 dywhere，與Update/Delete一樣，也是通過傳入的屬性解析到主鍵值獲取對應的數據。

那麼進入ISelect一探究竟吧：

暫且忽略多個泛型支持的方法：

T1 First()
TDto First();
TReturn First(Expression> select);
T1 ToOne();
TDto ToOne();
TReturn ToOne(Expression> select);
First和ToOne都是返回第一條數據
TDto 表示要查詢出來的字段合集，列名與數據表中一一對應
Expression> select 類型投影，通過lambda語句建立T1到TReturn之間的關係
返回多個：

List ToList(bool includeNestedMembers = false);
List ToList();
List ToList(Expression> select);
includeNestedMembers ： false: 返回 2級 LeftJoin/InnerJoin/RightJoin 對象；true: 返回所有 LeftJoin/InnerJoin/RightJoin的導航數據
其他方法：

long Count();// 返回數目
ISelect Distinct();//去重
ISelect Skip(int offset);// 忽略幾個
ISelect Take(int limit);// 獲取前幾個
ISelect OrderBy(Expression> column);// 排序
ISelect OrderBy(bool condition, Expression> column);// 排序
ISelect OrderByDescending(Expression> column); // 降序
ISelect OrderByDescending(bool condition, Expression> column);// 降序
decimal Sum(Expression> column);// 求和
double Avg(Expression> column);// 求平均數
設置查詢條件：

ISelect Where(Expression> exp);
ISelect WhereIf(bool condition, Expression> exp);
ISelect Where(string sql, object parms = null);
注意與dywhere之間是並列關係。

關於查詢FreeSql做了很多優化，更多內容可以查閱官方文檔。到目前爲止，這些方法已經可以滿足一個項目的使用了。

總結
FreeSql可以說結合了很多優秀的ORM框架內容，而且針對不同的方式分成了不同的插件形式，使主幹可以輕裝上陣。

這是官方文檔中關於不同使用習慣的介紹。

關於FreeSql的基礎內容就到這裏了，如果對FreeSql有更多的需求的話，可以踊躍吐槽哦~~如果有小夥伴還想看的話，我將會繼續爲大家講解的。

至此，2020-5-28 《C# 數據操作系列》暫時完結（如果後續有其他好的ORM的話，還會繼續更新的）。

原文地址https://www.cnblogs.com/c7jie/p/12986598.html

C# 數據操作系列 - 19 FreeSql 入坑介紹

DELETE FROM "Model" WHERE ("Id" = 1) AND ("Id" = 11)

UPDATE "Model" SET "Name" = @p_0 WHERE ("Id" = 1) AND ("Id" = 1)

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)

官宣！ASF官方正式宣佈Apache Hudi成爲頂級項目

關於C#委託三種調用的分享

C# 數據操作系列 - 19 FreeSql 入坑介紹

C++統一初始化語法（列表初始化）

Docker基礎修煉2--Docker鏡像原理及常用命令

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結