搭配 Xamarin.iOS 使用 SQLite.NET

發行項
03/08/2024

Xamarin 建議的 SQLite.NET 連結庫是基本的 ORM，可讓您在 iOS 裝置上的本機 SQLite 資料庫中儲存和擷取物件。 ORM 代表對象關係型對應 – 一種 API，可讓您從資料庫儲存和擷取「物件」，而不需要撰寫 SQL 語句。

使用方式

若要在 Xamarin 應用程式中包含 SQLite.NET 連結庫，請將下列 NuGet 套件新增至您的專案：

套件名稱： sqlite-net-pcl
作者： 弗蘭克·克魯格
識別碼：sqlite-net-pcl
Url：nuget.org/packages/sqlite-net-pcl

有許多不同的 SQLite 套件可用 – 請務必選擇正確的套件（可能不是搜尋中的最上層結果）。

重要

SQLite.NET 是 praeclarum/sqlite-net 存放庫所支援的第三方連結庫。

一旦您有可用的 SQLite.NET 連結庫，請遵循下列三個步驟來使用它來存取資料庫：

新增 using 語句 - 將下列語句新增至需要資料存取的 C# 檔案：
```
using SQLite;
```
建立空白資料庫 - 藉由傳遞 SQLite 連線 ion 類別建構函式的檔案路徑，即可建立資料庫參考。您不需要檢查檔案是否已經存在，否則將會視需要自動建立該檔案，否則將會開啟現有的資料庫檔案。
```
var db = new SQLiteConnection (dbPath);
```
dbPath 變數應該根據本檔稍早討論的規則來決定。
儲存數據 - 建立 SQLite 連線 ion 物件之後，會呼叫其方法來執行資料庫命令，例如 CreateTable 和 Insert，如下所示：
```
db.CreateTable<Stock> ();
db.Insert (newStock); // after creating the newStock object
```

擷取數據 - 若要擷取物件（或物件清單），請使用下列語法：

var stock = db.Get<Stock>(5); // primary key id of 5
var stockList = db.Table<Stock>();

基本數據存取範例

本 檔DataAccess_Basic 範例程式代碼在iOS上執行時看起來像這樣。此程式代碼說明如何執行簡單的 SQLite.NET 作業，並將結果顯示為應用程式主視窗中的文字。

iOS

下列程式代碼範例示範使用 SQLite.NET 連結庫來封裝基礎數據庫存取權的整個資料庫互動。它顯示：

建立資料庫檔案
藉由建立物件來插入某些數據，然後加以儲存
查詢資料

您必須包含這些命名空間：

using SQLite; // from the github SQLite.cs class

這需要您已將 SQLite 新增至專案，如此處醒目提示。請注意，SQLite 資料庫資料表是藉由將屬性新增至類別（ Stock 類別），而不是 CREATE TABLE 命令來定義。

[Table("Items")]
public class Stock {
    [PrimaryKey, AutoIncrement, Column("_id")]
    public int Id { get; set; }
    [MaxLength(8)]
    public string Symbol { get; set; }
}
public static void DoSomeDataAccess () {
       Console.WriteLine ("Creating database, if it doesn't already exist");
   string dbPath = Path.Combine (
        Environment.GetFolderPath (Environment.SpecialFolder.Personal),
        "ormdemo.db3");
   var db = new SQLiteConnection (dbPath);
   db.CreateTable<Stock> ();
   if (db.Table<Stock> ().Count() == 0) {
        // only insert the data if it doesn't already exist
        var newStock = new Stock ();
        newStock.Symbol = "AAPL";
        db.Insert (newStock);
        newStock = new Stock ();
        newStock.Symbol = "GOOG";
        db.Insert (newStock);
        newStock = new Stock ();
        newStock.Symbol = "MSFT";
        db.Insert (newStock);
    }
    Console.WriteLine("Reading data");
    var table = db.Table<Stock> ();
    foreach (var s in table) {
        Console.WriteLine (s.Id + " " + s.Symbol);
    }
}

[Table]在不指定數據表名稱參數的情況下使用屬性會導致基礎資料庫數據表的名稱與類別相同（在此案例中為“Stock” ）。如果您直接針對資料庫撰寫 SQL 查詢，而不是使用 ORM 數據存取方法，則實際數據表名稱很重要。同樣地，屬性是選擇性的 [Column("_id")] ，如果不存在數據行，則會加入與類別中屬性同名的數據表。

SQLite 屬性

您可以套用至類別的常見屬性，以控制它們儲存在基礎資料庫中的方式包括：

[PrimaryKey] – 這個屬性可以套用至整數屬性，以強制它成為基礎表的主鍵。不支持複合主鍵。
[AutoIncrement] – 這個屬性會導致插入資料庫中之每個新物件的整數屬性值自動遞增
[Column（name）] – 參數 name 會設定基礎資料庫數據行的名稱。
[Table（name）] – 將類別標示為能夠儲存在具有指定名稱的基礎 SQLite 數據表中。
[MaxLength（value）] – 嘗試插入資料庫時，限制 text 屬性的長度。使用程式代碼應該在插入物件之前先驗證這個值，因為只有在嘗試資料庫插入或更新作業時，才會檢查此屬性。
[忽略] – 導致 SQLite.NET 忽略這個屬性。這對於具有無法儲存在資料庫中之型別的屬性，或是無法自動解析為 SQLite 之模型集合的屬性特別有用。
[Unique] – 確保基礎資料庫數據列中的值是唯一的。

這些屬性大部分都是選擇性的。您應該一律指定整數主鍵，以便有效率地對數據執行選取和刪除查詢。

更複雜的查詢

上的下列方法 SQLiteConnection 可用來執行其他資料作業：

插入 – 將新的物件加入至資料庫。
取得<T> – 嘗試使用主鍵擷取物件。
數據表<T> – 傳回數據表中的所有物件。
Delete – 使用其主鍵刪除物件。
查詢<T> - 執行會傳回一些數據列的 SQL 查詢（作為物件）。
Execute – 當您不預期來自 SQL 的數據列（例如 INSERT、UPDATE 和 DELETE 指示）時，請使用此方法（而非 Query ）。

依主鍵取得物件

SQLite.Net 提供 Get 方法，以根據其主鍵擷取單一物件。

var existingItem = db.Get<Stock>(3);

使用 Linq 選取物件

傳回集合的方法支援 IEnumerable<T> ，讓您可以使用 Linq 來查詢或排序數據表的內容。下列程式代碼顯示使用 Linq 篩選出開頭為字母「A」的所有項目範例：

var apple = from s in db.Table<Stock>()
    where s.Symbol.StartsWith ("A")
    select s;
Console.WriteLine ("-> " + apple.FirstOrDefault ().Symbol);

使用 SQL 選取物件

雖然 SQLite.Net 可以提供以對象為基礎的數據存取，但有時您可能需要執行比 Linq 允許更複雜的查詢（或您可能需要更快的效能）。您可以使用 SQL 命令搭配 Query 方法，如下所示：

var stocksStartingWithA = db.Query<Stock>("SELECT * FROM Items WHERE Symbol = ?", "A");
foreach (var s in stocksStartingWithA) {
    Console.WriteLine ("a " + s.Symbol);
}

重要

直接撰寫 SQL 語句時，您會在資料庫中建立資料表和數據行名稱的相依性，這些名稱已從您的類別及其屬性產生。如果您在程式代碼中變更這些名稱，您必須記得更新任何手動撰寫的 SQL 語句。

刪除物件

主鍵可用來刪除資料列，如下所示：

var rowcount = db.Delete<Stock>(someStock.Id); // Id is the primary key

您可以檢查 rowcount 以確認有多少資料列受到影響（在此案例中已刪除）。

搭配多個線程使用 SQLite.NET

SQLite 支援三種不同的線程模式：單個線程、多線程和串行化。如果您想要從多個線程存取資料庫，但沒有任何限制，您可以將 SQLite 設定為使用 串行化 線程模式。請務必在應用程式早期設定此模式（例如，在方法的 OnCreate 開頭）。

若要變更線程模式，請呼叫 SqliteConnection.SetConfig 命名空間中的 Mono.Data.Sqlite 。例如，這一行程式代碼會針對 串行化 模式設定 SQLite：

using Mono.Data.Sqlite;
...
SqliteConnection.SetConfig(SQLiteConfig.Serialized);

共用方式為

搭配 Xamarin.iOS 使用 SQLite.NET

使用方式

基本數據存取範例

SQLite 屬性

更複雜的查詢

依主鍵取得物件

使用 Linq 選取物件

使用 SQL 選取物件

刪除物件

搭配多個線程使用 SQLite.NET

其他資源

共用方式為

搭配 Xamarin.iOS 使用 SQLite.NET

使用方式

基本數據存取範例

SQLite 屬性

更複雜的查詢

依主鍵取得物件

使用 Linq 選取物件

使用 SQL 選取物件

刪除物件

搭配多個線程使用 SQLite.NET

相關連結

其他資源