将脱机数据同步添加到 .NET MAUI 应用

项目
01/12/2024

注意

此产品已停用。有关使用 .NET 8 或更高版本的项目的替换，请参阅 Community Toolkit Datasync 库。

本教程介绍适用于 .NET MAUI 的 Azure 移动应用的脱机同步功能。脱机同步允许最终用户与移动应用交互，即使没有网络连接也是如此。更改存储在本地数据库中。设备重新联机后，这些更改会与远程后端同步。

在开始本教程之前，应已完成 .NET MAUI 快速入门教程，其中包括创建合适的后端服务。

若要了解有关脱机同步功能的详细信息，请参阅主题 Azure 移动应用中的脱机数据同步。

更新应用以支持脱机同步

在联机操作中，从 IRemoteTable<T>读取和写入。使用脱机同步时，可以改为从 IOfflineTable<T> 读取和写入。 IOfflineTable 由设备 SQLite 数据库提供支持，并与后端数据库同步。

在 Visual Studio 中：

右键单击 TodoApp 解决方案，然后选择 管理解决方案的 NuGet 包...。
在新选项卡中，选择浏览，然后在搜索框中输入 Microsoft.Datasync.Client。
选择 Microsoft.Datasync.Client.SQLiteStore 包。
在右侧窗格中，选择所有客户端项目（TodoAppService.NET6 项目除外）。
选择安装。
出现提示时接受许可协议。

更新远程服务客户端

打开 TodoApp.Data 项目，找到 RemoteTodoService.cs 类（在 Services 目录中）。按如下所示更新类：

将以下 using 语句添加到文件顶部：

using Microsoft.Datasync.Client.SQLiteStore;

将 _table 的定义更改为 IOfflineTable<TodoItem>：

/// <summary>
/// Reference to the table used for datasync operations.
/// </summary>
private IOfflineTable<TodoItem> _table = null;

添加用于存储脱机数据库位置的新属性：

/// <summary>
/// The path to the offline database
/// </summary>
public string OfflineDb { get; set; }

更新 InitializeAsync 方法以定义脱机数据库：

// Create the offline store definition
var connectionString = new UriBuilder { Scheme = "file", Path = OfflineDb, Query = "?mode=rwc" }.Uri.ToString();
var store = new OfflineSQLiteStore(connectionString);
store.DefineTable<TodoItem>();
var options = new DatasyncClientOptions
{
    OfflineStore = store,
    HttpPipeline = new HttpMessageHandler[] { new LoggingHandler() }
};

// Create the datasync client.
_client = TokenRequestor == null 
    ? new DatasyncClient(Constants.ServiceUri, options)
    : new DatasyncClient(Constants.ServiceUri, new GenericAuthenticationProvider(TokenRequestor), options);

// Initialize the database
await _client.InitializeOfflineStoreAsync();

// Get a reference to the offline table.
_table = _client.GetOfflineTable<TodoItem>();

// Set _initialized to true to prevent duplication of locking.
_initialized = true;

更新 RefreshItemsAsync() 以执行脱机同步：

/// <summary>
/// Refreshes the TodoItems list manually.
/// </summary>
/// <returns>A task that completes when the refresh is done.</returns>
public async Task RefreshItemsAsync()
{
    await InitializeAsync();

    // First, push all the items in the table.
    await _table.PushItemsAsync();

    // Then, pull all the items in the table.
    await _table.PullItemsAsync();

    return;
}

设置脱机数据库位置

在 TodoApp.MAUI 项目中，编辑 MainPage.xaml.cs 文件。更改 RemoteTodoService 的定义，如下所示：

TodoService = new RemoteTodoService(GetAuthenticationToken)
{
    OfflineDb = FileSystem.CacheDirectory + "/offline.db"
};

如果尚未完成身份验证教程，则定义应如下所示：

TodoService = new RemoteTodoService()
{
    OfflineDb = FileSystem.CacheDirectory + "/offline.db"
};

测试应用

在按下刷新图标之前，应用不会与后端同步。测试：

打开 Azure 门户。
打开包含快速入门资源的资源组。
选择 quickstart 数据库。
选择 查询编辑器（预览版）。
使用为数据库设置的相同凭据登录 SQL Server 身份验证。
- 如有必要，系统会提示你允许访问 IP 地址。选择链接以更新允许列表，然后按 “确定” 重试登录名。
在查询编辑器中，输入 SELECT * FROM [dbo].[TodoItems]。然后选择运行。

将显示当前 TodoItems 的列表。

S Q L 查询编辑器中结果的屏幕截图。

现在，通过应用进行一些更改。 不要按刷新（尚未）。

在 Azure 门户中重复 SQL 语句，并验证是否已对数据库中的数据进行更改。

选择应用上的刷新图标，将队列中的数据推送到后端服务。你将在“输出调试”窗口中看到 HTTP 事务发生。

在 Azure 门户中重复 SQL 语句，并验证更改是否已推送到远程服务。

清理资源

除非要执行另一个快速入门教程，否则现在可以删除与后端服务关联的资源。

打开 Azure 门户。
选择包含快速启动资源的资源组。
选择 删除资源组。
按照说明确认删除。

还可以使用 Azure CLI：

az group delete -g quickstart

如果使用 Azure 开发人员 CLI 部署资源，则可以改用 azd down 命令。

删除操作需要几分钟才能完成。

后续步骤

查看操作说明文档：
- ASP。NET6 服务文档
- .NET 客户端文档

通过