練習：使用 SQLite 在本機儲存資料

15 分鐘

在本練習中，您會在應用程式中使用 SQLite 在本機儲存資訊。在範例情節中，您決定快取社交媒體應用程式的資料，以提升回應力。本練習建立並使用本機 SQLite 資料庫來儲存人員相關資訊。您會將實體資料庫檔案儲存在本機儲存體。

本課程模組使用 .NET 9.0 SDK。確認您已在慣用的命令終端中執行下列命令來安裝 .NET 9.0：

dotnet --list-sdks

類似下列範例的輸出隨即出現：

8.0.100 [C:\Program Files\dotnet\sdk]
9.0.100 [C:\Program Files\dotnet\sdk]

確定已列出開頭為 9 的版本。如果未列出任何項目或找不到命令，請安裝最新的 .NET 9.0 SDK。

開啟入門解決方案

複製或下載練習存放庫。

注意

最好將練習內容複寫到簡短的資料夾路徑，例如 C:\dev，以避免組建產生的檔案超過路徑長度上限。
使用 Visual Studio 開啟 People.sln 方案，您可以在 mslearn-dotnetmaui-store-local-data > [人員]，或 Visual Studio Code 中的入門資料夾中找到。

注意

請勿立即嘗試執行應用程式，程式碼不完整，而且會擲回例外狀況，直到您稍後在此練習中新增遺漏的項目為止。

定義 SQLite 實體

在 Models 資料夾中開啟 Person.cs 檔案。
將名為 Id 的 int 屬性新增至 Person 類別。

新增一個稱為 Name 的 string 屬性。該類別看起來應該如下所示：

namespace People.Models;

public class Person
{
    public int Id { get; set; }
    public string Name { get; set; }
}

儲存 Person.cs 檔案。

新增 SQLite 程式庫

在 Visual Studio 中，從 [方案總管] 中以滑鼠右鍵按一下 [People] 專案節點。
在出現的捷徑功能表中，選取 [管理 NuGet 套件]。
搜尋並選取 sqlite-net-pcl，然後選取 [安裝]。

如果使用 Visual Studio Code，請使用下列命令開啟終端機和這些套件：

dotnet add package sqlite-net-pcl

新增 SQLite 屬性

在 Person.cs 檔案中，將 SQLite 命名空間的 using 指示詞新增至 Person 類別的檔案。此指示詞可讓您使用 SQLite 屬性。
```
using SQLite;

namespace People.Models;

public class Person
{
    ...
}
```
使用 [Table] 屬性標注 Person 類別，並將資料表名稱指定為 people。
將 Id 屬性指定為主索引鍵。使用 [PrimaryKey] 和 [AutoIncrement] 屬性作為標注。

新增 Name 屬性的註釋。將其 MaxLength 指定為 250。指定資料行中的每個值應為 Unique。

完整的類別如下所示：

using SQLite;

namespace People.Models;

[Table("people")]
public class Person
{
    [PrimaryKey, AutoIncrement]
    public int Id { get; set; }

    [MaxLength(250), Unique]
    public string Name { get; set; }
}

儲存 Person.cs 檔案。

連接至資料庫

開啟 PersonRepository.cs 檔案。
檢查 PersonRepository 類別。此類別包含不完整的骨架程式碼，TODO 標記處由您新增功能來存取資料庫。
將 SQLite 和 People.Models 命名空間的 using 指示詞新增至 PersonRepository.cs 類別的檔案。
將名為 conn 的私人 SQLiteConnection 欄位新增至類別，高於 Init 函式。
在 Init 函式中，檢查 conn 是否不等於 null。若是如此，則立即返回。
```
if (conn != null)
    return;
```
這樣 SQLite 資料庫的初始化程式碼只會執行一次。
初始化 conn 欄位，以使用 _dbPath 變數連線到資料庫。

使用 conn.CreateTable 方法建立資料表以儲存 Person 資料。完整的 Init 函式如下所示：

using SQLite;
using People.Models;
...

private SQLiteConnection conn;
...
private void Init()
{
   if (conn != null)
      return;

   conn = new SQLiteConnection(_dbPath);
   conn.CreateTable<Person>();
}

將資料列插入資料庫

在 PersonRepository 類別中，尋找 AddNewPerson 方法。

若要插入新的 Person 物件，請以程式碼取代此方法中的 TODO 註解。程式碼會先呼叫 Init 以確認資料庫已初始化，然後使用 SQLiteConnection 物件的 Insert 方法。將 result 變數設定為 Insert 方法傳回的值，如下列程式碼所示：

public void AddNewPerson(string name)
{
    int result = 0;
    try
    {
        // enter this line
        Init();

        // basic validation to ensure a name was entered
        if (string.IsNullOrEmpty(name))
            throw new Exception("Valid name required");

        // enter this line
        result = conn.Insert(new Person { Name = name });
        ...
    }
    ...
}

從資料庫擷取資料列

在 PersonRepository 類別中找到 GetAllPeople 方法。
呼叫 Init 以確認資料庫已初始化。
使用泛型 Table\<T> 方法來擷取資料表中的所有資料列。將 Person 指定為型別參數。
使用 ToList() 擴充方法，將結果轉換成 List\<Person> 集合，並傳回這個集合。

以 try-catch 區塊包裝程式碼來新增錯誤處理。如果發生錯誤，請將 StatusMessage 屬性設定為例外狀況的 Message 屬性，並傳回空的集合。完整的方法如下所示：

public List<Person> GetAllPeople()
{
   try
   {
      Init();
      return conn.Table<Person>().ToList();
   }
   catch (Exception ex)
   {
      StatusMessage = string.Format("Failed to retrieve data. {0}", ex.Message);
   }

   return new List<Person>();
}

儲存 PersonRepository.cs 檔案。

將存放庫整合至 UI

開啟 MauiProgram.cs 檔案。
在 CreateMauiApp 函式中，將 MainPage 頁面新增為單一資料庫服務的陳述式之後，新增程式碼以執行下列工作：
- 建立名為 dbPath 的字串變數。以運算式 FileAccessHelper.GetLocalFilePath("people.db3") 來初始化此字串。應用程式使用的資料庫檔案稱為 people.db3，應用程式會將此檔案儲存在裝置上的本機存放區。
- 使用相依性注入，將 PersonRepository 類別當成單一服務新增至應用程式。 PersonRepository 類別公開的建構函式將資料庫檔案的路徑當作字串參數。
CreateMauiApp 函式已完成的程式碼看起來應該像這樣：
```
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        });

    // Add this code
    string dbPath = FileAccessHelper.GetLocalFilePath("people.db3");
    builder.Services.AddSingleton<PersonRepository>(s => ActivatorUtilities.CreateInstance<PersonRepository>(s, dbPath));

    return builder.Build();
}
```
儲存 MauiProgram.cs 檔案。
展開 [方案總管] 中的 App.xaml，然後開啟 App.xaml.cs 檔案。
新增 public，這是一個稱為 PersonRepo 的 static 屬性。這個屬性會將 PersonRepository 物件保存至 App 類別。

將 PersonRepository 參數新增至建構函式，並將 'PersonRepo' 屬性設定為此參數中的值，以初始化建構函式中的 PersonRepo 屬性。完整的 App 類別看起來應該像這樣：

public partial class App : Application
{
    public static PersonRepository PersonRepo { get; private set; }

    public App(PersonRepository repo)
    {
        InitializeComponent();
        PersonRepo = repo;
    }
}

注意

相依性注入程序會自動將 repo 參數填入建構函式。

測試應用程式

使用 CTRL+Shift+B 來建置解決方案。
建置完成後，請使用 F5 開始偵錯。當 UI 出現時，請輸入您的名稱，並選取 [新增人員]。
選取 [取得所有人員]，並確認您的名稱出現。
嘗試新增更多名稱並擷取已儲存的人員清單。
返回 Visual Studio 或 Visual Studio Code，並使用 Shift+F5 停止偵錯。
重新啟動應用程式，然後選取 [取得所有人員]。確認您先前儲存的名稱仍儲存在資料庫中。完成後，請關閉應用程式。