目錄
- 簡介
- 快速入門
- 安裝 NuGet 包
- 實體類User
- 資料庫類DbFactory
- 增刪改查
- Insert
- Select
- Update
- Delete
- 總結
簡介
NPoco 是 PetaPoco 的一個分支，具有一些額外的功能，截至現在 github 星數 839。NPoco 中文資料沒多少，我是被部落格園群友推薦的，這幾天簡單嘗試了一下：
github: https://github.com/schotime/NPoco
wiki: https://github.com/schotime/NPoco/wiki
NPoco 支援多種資料庫系統，包括但不限於以下幾種：
- Microsoft SQL Server
- SQLite
- MySQL
- PostgreSQL
- Oracle
- Firebird
- DB2
- SQL CE (SQL Compact Edition)
快速入門
本文使用SQLite資料庫作為示例，建立一個控制檯專案，嘗試一些簡單的用法。
安裝 NuGet 包
對於使用 NPoco 和 SQLite 的情況，只需要安裝兩個 NuGet 包：
- NPoco - 這是 NPoco ORM 的核心庫。
- System.Data.SQLite 或 Microsoft.Data.Sqlite - 這是用於連線 SQLite 資料庫的 ADO.NET 提供程式。
選擇 System.Data.SQLite 或 Microsoft.Data.Sqlite 主要取決於正在使用的 .NET 平臺：
- .NET Core 3.1 或 .NET 5/6/7 的專案選擇 Microsoft.Data.Sqlite
- .NET Framework 或早期的 .NET Core 版本的專案選擇 System.Data.SQLite
這裡使用 Microsoft.Data.Sqlite ，NuGet 包安裝如下：
實體類User
新建一個實體類 User ，並定義實體類和欄位的對映關係，參考 官方文件 Mapping：
//為了演示 TableName、Column ，表名和列名故意和實體類的屬性名設定的不同
[TableName("Users")]
[PrimaryKey("UserId", AutoIncrement = true)]
public class User
{
public int UserId { get; set; }
[Column("Email")]
public string UserEmail { get; set; }
[ComputedColumn]
public DateTime CreateTime{ get; set; }
[ComputedColumn]
public DateTime UpdateTime { get;set; }
// 重寫 ToString 方法，列印實體類資訊
public override string ToString()
{
//SQLite儲存日期和時間的方式是以UTC（協調世界時）為基準的，列印時需要轉換成本地時間
return $"UserId: {UserId}, " +
$"Email: {UserEmail}," +
$" CreatedTime: {CreateTime.ToLocalTime()}," +
$" UpdateTime: {UpdateTime.ToLocalTime()}";
}
}
上面用到的 TableName、PrimaryKey、Column 特性根據字面意思很容易理解，需要特別注意 ComputedColumn 相關的三個特性：
- [Ignore] ：此屬性將被忽略，並且無法對映到此屬性，可以定義一些跟資料庫無關但業務需要的屬性。
- [ResultColumn] ：可以對映到標有 ResultColumn 列的屬性，但這些屬性不會包含在插入或更新中。需要在 SQL 中顯式指定這些列，它不會包含在自動生成的 SQL 中。
- [ComputedColumn] ：具有 Computed 列屬性的屬性的工作方式與 Result 列屬性相同，但是它們將在 SQL 中自動選擇。
資料庫類DbFactory
定義一個 DbFactory 類管理連線字串和資料庫例項，對映部分請參考 基於 Fluent / Convention 的對映：
public static class DbFactory
{
private static DatabaseFactory dbFactory;
public static Database GetDatabase()
{
return dbFactory.GetDatabase();
}
static DbFactory()
{
dbFactory = DatabaseFactory.Config(x =>
{
// 也可以在這裡配置實體的對映關係
x.UsingDatabase(() => new Database(
"Data Source=mydatabase.db;",
DatabaseType.SQLite,
SqliteFactory.Instance)
);
});
InitDB();
}
static void InitDB()
{
// 建立資料庫檔案
File.Create("mydatabase.db").Close();
// 建立表
using (IDatabase db = dbFactory.GetDatabase())
{
db.Execute(@"
-- 建立Users表
CREATE TABLE IF NOT EXISTS Users (
UserId INTEGER PRIMARY KEY AUTOINCREMENT,
Email TEXT,
CreateTime TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UpdateTime TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 建立觸發器，在Users 表上的資料更新後自動更新 UpdateTime 欄位
CREATE TRIGGER IF NOT EXISTS update_user_time
AFTER UPDATE OF Email, CreateTime ON Users
BEGIN
UPDATE Users SET UpdateTime = CURRENT_TIMESTAMP WHERE rowid = NEW.rowid;
END;"
);
}
}
}
SQLite 並不直接支援在列定義中使用 ON UPDATE 語法，需要建立一個觸發器在 Users 表上更新操作發生時自動更新 UpdateTime 欄位。觸發器觸發時為了避免重新觸發自身（遞迴觸發），要僅在 UpdateTime 之外的欄位被更新時才觸發。
增刪改查
下面演示一下 Insert、Update、Delete、Query 等操作，主程式如下：
static void Main(string[] args)
{
Insert();
Select();
Thread.Sleep(3000);
Update();
Delete();
}
Insert
建立一個 Insert 方法，實現單次插入和批次插入：
static void Insert()
{
using (IDatabase db = DbFactory.GetDatabase())
{
Console.WriteLine("單次插入：");
var user = new User { UserEmail = $"test@example.com" };
db.Insert(user);
Console.WriteLine(user.ToString());
Console.WriteLine("批次插入：");
List<User> users = new List<User>();
for (int i = 0; i < 5; i++)
{
user = new User { UserEmail = $"test{i}@example.com" };
users.Add(user);
}
var count = db.InsertBatch(users);
Console.WriteLine($"批次插入 {count} 條記錄");
Console.WriteLine();
}
}
Select
建立一個 Select 方法，實現常見的查詢方法：
static void Select()
{
using (IDatabase db = DbFactory.GetDatabase())
{
Console.WriteLine("查詢所有使用者：");
var users = db.Fetch<User>();
users.ForEach(user => Console.WriteLine(user.ToString()));
Console.WriteLine("使用SQL語句查詢：");
//下面兩種方式都可以
users = db.Query<User>("SELECT * FROM Users WHERE Email LIKE @0", "%@example.com").ToList();
users = db.Query<User>("WHERE Email LIKE @0", "%@example.com").ToList();
users.ForEach(user => Console.WriteLine(user.ToString()));
Console.WriteLine("使用LINQ語句查詢ID大於1的使用者，並按ID排序：");
//推薦用法LINQ語句查詢
users = db.Query<User>()
.Where(x => x.UserId > 1)
.OrderBy(x => x.UserId)
.ToList();
users.ForEach(user => Console.WriteLine(user.ToString()));
Console.WriteLine("透過ID查詢單個使用者：");
//SingleById還有很多變體，這裡不在單獨舉例
var user = db.SingleOrDefaultById<User>(1);
Console.WriteLine(user.ToString());
Console.WriteLine();
}
}
注意：如果找不到記錄，SingleById()方法會丟擲異常，而 SingleOrDefaultById() 方法會返回 null，推薦使用 SingleOrDefaultById() 方法。
Update
建立一個 Update 方法，實現單個使用者更新和批次更新：
static void Update()
{
using (IDatabase db = DbFactory.GetDatabase())
{
Console.WriteLine("更新單個使用者：");
var user = db.SingleById<User>(1);
user.UserEmail = "updated@example.com";
db.Update(user);
Console.WriteLine(db.SingleById<User>(1).ToString());
Console.WriteLine("批次更新 ID > 3 的使用者：");
var users = db.Query<User>()
.Where(x => x.UserId > 3).ToList()
.Select(x => UpdateBatch.For(x, db.StartSnapshot(x))).ToList()
.Select(x => { x.Poco.UserEmail = "updated@example.com"; return x; })
.ToList();
db.UpdateBatch(users, new BatchOptions { BatchSize = 50 });
db.Fetch<User>().ForEach(user => Console.WriteLine(user.ToString()));
Console.WriteLine();
}
}
注意：關於 UpdateBatch 方法的使用，官方文件沒有詳細說明，使用方法可以參考 UpdateTests
Delete
建立一個 Delete 方法，實現單個使用者刪除和批次刪除：
static void Delete()
{
using (IDatabase db = DbFactory.GetDatabase())
{
Console.WriteLine("刪除單個使用者：");
var user = db.SingleById<User>(1);
db.Delete(user);
Console.WriteLine($"刪除使用者 {user.ToString()} 成功");
Console.WriteLine("使用SQL構造器刪除 Id > 4 的：");
var sql = new Sql();
sql.Append("DELETE FROM Users WHERE UserId > @0", 4);
var count=db.Execute(sql);
Console.WriteLine($"刪除 {count} 條記錄");
Console.WriteLine("使用SQL語句刪除 Id > 3 的：");
count = db.Delete<User>("WHERE UserId > @0", 3);
Console.WriteLine($"刪除 {count} 條記錄");
}
}
總結
一些簡單功能上手比較容易，程式碼侵入性也比較小。複雜一點的功能上手比較難，因為中文資料少、官方文件也有點落後。
一般的小專案或者小功能模組可以使用NPoco，大專案還是建議使用國產的FreeSQL、SqlSugar。