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的話，還會繼續更新的），

更多內容煩請關注我的博客《高先生小屋》

file

轉載請註明出處，本文鏈接：https://www.uj5u.com/net/26970.html

標籤：C#

上一篇：C# 無邊框的表單怎么放大縮小表單啊

下一篇：【asp.net core 系列】 1 帶你了解一下asp.net core

C# 資料操作系列 - 19 FreeSql 入坑介紹