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

時間 2021-02-27

標籤 sql 數據庫 app 框架 ide 測試優化 this spa 欄目 C# 简体版

原文原文鏈接

0. 前言

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

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

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

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

1. 初步使用

照例，沒安裝就沒有調用。因此，在建立項目以後，安裝一下吧：ide

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表示該屬性是一個只能讀的屬性（與只讀屬性有個微妙的差距），等號後面表示該屬性第一次賦值的內容。ui

建立一個普通的Model類：this

public class Model
{
    public int Id { get; set; }
    public int StringLength { get; set; }
    public string Name { get; set; }
}

1.1 簡單插入

而後試一下插入數據：spa

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> exp 表示在字段自己值的基礎上進行操做</func
Expression
<func> column, TMember value 表示將 column設置 value</func
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> select 類型投影，經過lambda語句創建T1到TReturn之間的關係</func

返回多個：

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作了不少優化，更多內容能夠查閱官方文檔。到目前爲止，這些方法已經能夠知足一個項目的使用了。