Xamarin.Forms 本地数据库教程

开始演练本教程的前提条件为已成功完成以下教程：

生成第一个 Xamarin.Forms 应用快速入门。
StackLayout教程。
按钮教程。
输入教程。
CollectionView 教程。

在本教程中，你将了解如何执行以下操作：

使用 NuGet 包管理器将 SQLite.NET 添加到 Xamarin.Forms 项目中。
创建数据访问类。
使用数据访问类。

你将使用 Visual Studio 2019 或 Visual Studio for Mac 创建一个简单的应用程序，演示如何将数据存储在本地 SQLite.NET 数据库中。以下屏幕截图显示了最终的应用程序：

添加 SQLite.NET

剩余 11 分钟

Visual Studio
Visual Studio for Mac

若要完成本教程，应使用 Visual Studio 2019（最新版本），且安装了“使用 .NET 的移动开发”工作负载。此外，还需要一个匹配的 Mac，用于在 iOS 上生成教程应用程序。有关安装 Xamarin 平台的信息，请参阅安装 Xamarin。有关将 Visual Studio 2019 连接到 Mac 生成主机的信息，请参阅通过“与 Mac 配对”进行 Xamarin.iOS 开发。

启动 Visual Studio，新建名为 LocalDatabaseTutorial 的 Xamarin.Forms 空白应用。

重要

本教程中的 C# 和 XAML 片段要求将解决方案命名为 LocalDatabaseTutorial。使用不同的名称会导致：将本教程中的代码复制到解决方案中时出现生成错误。

有关创建的 .NET Standard 库的详细信息，请参阅 Xamarin.FormsXamarin.Forms 快速入门的深入探讨中的 Xamarin.Forms 应用程序剖析。
在“解决方案资源管理器”中，选择 LocalDatabaseTutorial 项目，然后右键单击并选择“管理 NuGet 包…” ：
在“NuGet 包管理器”中，选择“浏览”选项卡，搜索“sqlite-net-pcl”NuGet 包，选择它，然后单击“安装”按钮将其添加到项目：
注意

许多 NuGet 包都有着类似的名称。正确的包具有以下属性：
- 作者：SQLite-net
- NuGet 链接：sqlite-net-pcl
尽管包的名称如此，此 NuGet 包也可以用于 .NET Standard 项目。
此包将用于将数据库操作合并到应用程序。

重要

SQLite.NET 是 praeclarum/sqlite-net 存储库支持的第三方库。
生成解决方案，确保没有任何错误。

创建数据访问类

剩余 8 分钟

在本练习中，你将向 LocalDatabaseTutorial 项目添加数据访问类，用于将人员相关数据保存到数据库中。

Visual Studio
Visual Studio for Mac

在解决方案资源管理器的 LocalDatabaseTutorial 项目中，向该项目添加名为 Person 的新类。然后，在 Person.cs 中，删除所有模板代码，替换为以下代码：
```
using SQLite;

namespace LocalDatabaseTutorial
{
    public class Person
    {
        [PrimaryKey, AutoIncrement]
        public int ID { get; set; }
        public string Name { get; set; }
        public int Age { get; set; }
    }
}
```
此代码定义 Person 类，该类将在应用程序中存储关于每个人的数据。使用 PrimaryKey 和 AutoIncrement 特性标记 ID 属性，以确保数据库中的每个 Person 实例均具有 SQLite.NET 提供的惟一 ID。

在解决方案资源管理器的 LocalDatabaseTutorial 项目中，向该项目添加名为 Database 的新类。然后，在 Database.cs 中，删除所有模板代码并替换为以下代码：

using System.Collections.Generic;
using System.Threading.Tasks;
using SQLite;

namespace LocalDatabaseTutorial
{
    public class Database
    {
        readonly SQLiteAsyncConnection _database;

        public Database(string dbPath)
        {
            _database = new SQLiteAsyncConnection(dbPath);
            _database.CreateTableAsync<Person>().Wait();
        }

        public Task<List<Person>> GetPeopleAsync()
        {
            return _database.Table<Person>().ToListAsync();
        }

        public Task<int> SavePersonAsync(Person person)
        {
            return _database.InsertAsync(person);
        }
    }
}

此类包含用于创建数据库、从中读取数据和向其写入数据的代码。代码使用将数据库操作移动到后台线程的异步 SQLite.NET API。此外，Database 构造函数将数据库文件的路径作为参数。在下一个练习中，此路径由 App 类提供。

在解决方案资源管理器的 LocalDatabaseTutorial 项目中，展开 App.xaml，然后双击 App.xaml.cs 将其打开。然后在“App.xaml.cs”中，删除所有模板代码并替换为以下代码：

using System;
using System.IO;
using Xamarin.Forms;

namespace LocalDatabaseTutorial
{
    public partial class App : Application
    {
        static Database database;

        public static Database Database
        {
            get
            {
                if (database == null)
                {
                    database = new Database(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "people.db3"));
                }
                return database;
            }
        }

        public App()
        {
            InitializeComponent();

            MainPage = new MainPage();
        }

        protected override void OnStart()
        {
            // Handle when your app starts
        }

        protected override void OnSleep()
        {
            // Handle when your app sleeps
        }

        protected override void OnResume()
        {
            // Handle when your app resumes
        }
    }
}

此代码定义新建 Database 实例作为单一实例的 Database 属性。表示数据库存储位置的本地文件路径和文件名被作为参数传递给 Database 类构造函数。

重要

以单一实例的形式公开数据库的优势是，所创建的单一数据库连接在应用程序运行时保持打开状态，因此避免了每次执行数据库操作时打开和关闭数据库文件所产生的费用。

生成解决方案，确保没有任何错误。

在 Solution Pad 的 LocalDatabaseTutorial 项目中，向该项目添加名为 Person 的新类。然后，在 Person.cs 中，删除所有模板代码，替换为以下代码：
```
using SQLite;

namespace LocalDatabaseTutorial
{
    public class Person
    {
        [PrimaryKey, AutoIncrement]
        public int ID { get; set; }
        public string Name { get; set; }
        public int Age { get; set; }
    }
}
```
此代码定义 Person 类，该类将在应用程序中存储关于每个人的数据。使用 PrimaryKey 和 AutoIncrement 特性标记 ID 属性，以确保数据库中的每个 Person 实例均具有 SQLite.NET 提供的惟一 ID。

在 Solution Pad 的 LocalDatabaseTutorial 项目中，向该项目添加名为 Database 的新类。然后，在 Database.cs 中，删除所有模板代码并替换为以下代码：

using System.Collections.Generic;
using System.Threading.Tasks;
using SQLite;

namespace LocalDatabaseTutorial
{
    public class Database
    {
        readonly SQLiteAsyncConnection _database;

        public Database(string dbPath)
        {
            _database = new SQLiteAsyncConnection(dbPath);
            _database.CreateTableAsync<Person>().Wait();
        }

        public Task<List<Person>> GetPeopleAsync()
        {
            return _database.Table<Person>().ToListAsync();
        }

        public Task<int> SavePersonAsync(Person person)
        {
            return _database.InsertAsync(person);
        }
    }
}

此类包含用于创建数据库、从中读取数据和向其写入数据的代码。代码使用将数据库操作移动到后台线程的异步 SQLite.NET API。此外，Database 构造函数将数据库文件的路径作为参数。在下一个练习中，此路径由 App 类提供。

在 Solution Pad 的 LocalDatabaseTutorial 项目中，展开 App.xaml，然后双击 App.xaml.cs 将其打开。然后在“App.xaml.cs”中，删除所有模板代码并替换为以下代码：

using System;
using System.IO;
using Xamarin.Forms;

namespace LocalDatabaseTutorial
{
    public partial class App : Application
    {
        static Database database;

        public static Database Database
        {
            get
            {
                if (database == null)
                {
                    database = new Database(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "people.db3"));
                }
                return database;
            }
        }

        public App()
        {
            InitializeComponent();

            MainPage = new MainPage();
        }

        protected override void OnStart()
        {
            // Handle when your app starts
        }

        protected override void OnSleep()
        {
            // Handle when your app sleeps
        }

        protected override void OnResume()
        {
            // Handle when your app resumes
        }
    }
}

此代码定义新建 Database 实例作为单一实例的 Database 属性。表示数据库存储位置的本地文件路径和文件名被作为参数传递给 Database 类构造函数。

重要

以单一实例的形式公开数据库的优势是，所创建的单一数据库连接在应用程序运行时保持打开状态，因此避免了每次执行数据库操作时打开和关闭数据库文件所产生的费用。

生成解决方案，确保没有任何错误。

使用数据访问类

剩余 3 分钟

在本练习中，你将创建一个用户界面来使用以前创建的数据访问类。

Visual Studio
Visual Studio for Mac

在“解决方案资源管理器”的 LocalDatabaseTutorial 项目中，双击 MainPage.xaml 将其打开。然后在 MainPage.xaml 中，删除所有模板代码，替换为以下代码：

<?xml version="1.0" encoding="utf-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="LocalDatabaseTutorial.MainPage">
    <StackLayout Margin="20,35,20,20">
        <Entry x:Name="nameEntry"
               Placeholder="Enter name" />
        <Entry x:Name="ageEntry"
               Placeholder="Enter age" />
        <Button Text="Add to Database"
                Clicked="OnButtonClicked" />
        <CollectionView x:Name="collectionView">
            <CollectionView.ItemTemplate>
                <DataTemplate>
                    <StackLayout>
                        <Label Text="{Binding Name}"
                               FontSize="Medium" />
                        <Label Text="{Binding Age}"
                               TextColor="Silver"
                               FontSize="Small" />
                    </StackLayout>
                </DataTemplate>
            </CollectionView.ItemTemplate>
        </CollectionView>
    </StackLayout>
</ContentPage>

此代码以声明方式定义页面的用户界面，该界面由两个 Entry 实例、一个 Button 和 StackLayout 中的一个 CollectionView 组成。每个 Entry 都有其 Placeholder 属性集，用于指定在用户输入之前显示的占位符文本。 Button 将其 Clicked 事件设置为名为 OnButtonClicked 的事件处理程序，将在下一步中创建该处理程序。 CollectionView 将其 ItemTemplate 属性设置为 DataTemplate，后者使用 StackLayout 和两个 Label 对象来定义 CollectionView 中每一行的外观。 Label 对象将其 Text 分别绑定到每个 Person 对象的 Name 和 Age 属性。

此外，Entry 实例和 CollectionView 具有使用 x:Name 属性指定的名称。该操作使代码隐藏文件可以使用指定的名称访问这些对象。

在“解决方案资源管理器”的 LocalDatabaseTutorial 项目中，展开“MainPage.xaml”，然后双击“MainPage.xaml.cs”将其打开。然后在 MainPage.xaml.cs 中，将 OnAppearing 替代和 OnButtonClicked 事件处理程序添加到类：
```
protected override async void OnAppearing()
{
    base.OnAppearing();
    collectionView.ItemsSource = await App.Database.GetPeopleAsync();
}

async void OnButtonClicked(object sender, EventArgs e)
{
    if (!string.IsNullOrWhiteSpace(nameEntry.Text) && !string.IsNullOrWhiteSpace(ageEntry.Text))
    {
        await App.Database.SavePersonAsync(new Person
        {
            Name = nameEntry.Text,
            Age = int.Parse(ageEntry.Text)
        });

        nameEntry.Text = ageEntry.Text = string.Empty;
        collectionView.ItemsSource = await App.Database.GetPeopleAsync();
    }
}
```
OnAppearing 方法使用存储在数据库中的任何数据填充 CollectionView。点击 Button 时执行的 OnButtonClicked 方法会在清除 Entry 实例并刷新 CollectionView 中的数据之前将输入的数据保存到数据库中。

注意

OnAppearing 方法覆盖的执行是在布局 ContentPage 后但在其变得可见之前进行的。因此，这是设置 Xamarin.Forms 视图内容的好地方。
在 Visual Studio 工具栏中，按“开始”按钮（类似“播放”按钮的三角形按钮），启动所选远程 iOS 模拟器或 Android Emulator 内的应用程序。

输入多项数据，为每项数据点击 Button。这会将数据保存到数据库，并使用所有数据库数据重新填充 CollectionView：

在 Visual Studio 中停止应用程序。

如需详细了解 Xamarin.Forms 中的本地存储库，请参阅 Xamarin.Forms 本地存储库（指南）

在“Solution Pad”的 LocalDatabaseTutorial 项目中，双击 MainPage.xaml 将其打开。然后在 MainPage.xaml 中，删除所有模板代码，替换为以下代码：

<?xml version="1.0" encoding="utf-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="LocalDatabaseTutorial.MainPage">
    <StackLayout Margin="20,35,20,20">
        <Entry x:Name="nameEntry"
               Placeholder="Enter name" />
        <Entry x:Name="ageEntry"
               Placeholder="Enter age" />
        <Button Text="Add to Database"
                Clicked="OnButtonClicked" />
        <CollectionView x:Name="collectionView">
            <CollectionView.ItemTemplate>
                <DataTemplate>
                    <StackLayout>
                        <Label Text="{Binding Name}"
                               FontSize="Medium" />
                        <Label Text="{Binding Age}"
                               TextColor="Silver"
                               FontSize="Small" />
                    </StackLayout>
                </DataTemplate>
            </CollectionView.ItemTemplate>
        </CollectionView>
    </StackLayout>
</ContentPage>

此代码以声明方式定义页面的用户界面，该界面由两个 Entry 实例、一个 Button 和 StackLayout 中的一个 CollectionView 组成。每个 Entry 都有其 Placeholder 属性集，用于指定在用户输入之前显示的占位符文本。 Button 将其 Clicked 事件设置为名为 OnButtonClicked 的事件处理程序，将在下一步中创建该处理程序。 CollectionView 将其 ItemTemplate 属性设置为 DataTemplate，后者使用 StackLayout 和两个 Label 对象来定义 CollectionView 中每一行的外观。 Label 对象将其 Text 分别绑定到每个 Person 对象的 Name 和 Age 属性。

此外，Entry 实例和 ListView 具有使用 x:Name 属性指定的名称。该操作使代码隐藏文件可以使用指定的名称访问这些对象。

在“Solution Pad”的 LocalDatabaseTutorial 项目中，展开“MainPage.xaml”，然后双击“MainPage.xaml.cs”将其打开。然后在 MainPage.xaml.cs 中，将 OnAppearing 替代和 OnButtonClicked 事件处理程序添加到类：
```
protected override async void OnAppearing()
{
    base.OnAppearing();
    collectionView.ItemsSource = await App.Database.GetPeopleAsync();
}

async void OnButtonClicked(object sender, EventArgs e)
{
    if (!string.IsNullOrWhiteSpace(nameEntry.Text) && !string.IsNullOrWhiteSpace(ageEntry.Text))
    {
        await App.Database.SavePersonAsync(new Person
        {
            Name = nameEntry.Text,
            Age = int.Parse(ageEntry.Text)
        });

        nameEntry.Text = ageEntry.Text = string.Empty;
        collectionView.ItemsSource = await App.Database.GetPeopleAsync();
    }
}
```
OnAppearing 方法使用存储在数据库中的任何数据填充 CollectionView。点击 Button 时执行的 OnButtonClicked 方法会在清除 Entry 实例并刷新 CollectionView 中的数据之前将输入的数据保存到数据库中。

注意

OnAppearing 方法覆盖的执行是在布局 ContentPage 后但在其变得可见之前进行的。因此，这是设置 Xamarin.Forms 视图内容的好地方。
在 Visual Studio for Mac 工具栏中，按“开始”按钮（类似“播放”按钮的三角形按钮），启动所选 iOS 模拟器或 Android Emulator 内的应用程序。

输入多项数据，为每项数据点击 Button。这会将数据保存到数据库，并使用所有数据库数据重新填充 CollectionView：

在 Visual Studio for Mac 中停止应用程序。

如需详细了解 Xamarin.Forms 中的本地存储库，请参阅 Xamarin.Forms 本地存储库（指南）

恭喜！

100% 完成！

祝贺你完成了本教程的学习，在本教程中你学习了如何：

使用 NuGet 包管理器将 SQLite.NET 添加到 Xamarin.Forms 项目中。
创建数据访问类。
使用数据访问类。

后续步骤

若要深入了解使用 Xamarin.Forms 创建移动应用程序的基础知识，请继续学习“Web 服务”教程。

Web 服务教程

通过

添加 SQLite.NET

创建数据访问类

使用数据访问类

恭喜！

后续步骤

相关链接