啟用 Xamarin.Forms 行動應用程式的離線同步處理

發行項
2019-06-25

概觀

本教學課程介紹適用於 Xamarin.Forms 的 Azure Mobile Apps 離機同步處理功能。離線同步處理可讓使用者與行動裝置應用程式互動--檢視、新增或修改數據，即使沒有網路連線也是如此。變更會儲存在本機資料庫中。裝置重新上線后，這些變更會與遠端服務同步。

本教學課程是以您完成教學課程 [建立 Xamarin iOS 應用程式] 時所建立之 Mobile Apps 的 Xamarin.Forms 快速入門解決方案為基礎。 Xamarin.Forms 的快速入門解決方案包含支持離線同步的程式代碼，只需要啟用。在本教學課程中，您會更新快速入門解決方案，以開啟 Azure Mobile Apps 的離線功能。我們也會強調應用程式中的特定離線程式碼。如果您未使用下載的快速入門解決方案，您必須將資料存取延伸模組套件新增至專案。如需有關伺服器擴充套件的更多資訊，請參閱使用適用於 Azure 行動應用的 .NET 後台伺服器 SDK。

若要深入瞭解離線同步功能，請參閱在 Azure Mobile Apps 中離線數據同步主題。

在快速入門解決方案中啟用離線同步處理功能

離線同步處理程式碼會使用 C# 預處理器指示詞包含在專案中。定義 OFFLINE_SYNC_ENABLED 符號時，這些程式代碼路徑會包含在組建中。針對 Windows 應用程式，您也必須安裝 SQLite 平臺。

在 Visual Studio 中，以滑鼠右鍵按兩下方案 >[管理方案的 NuGet 套件...]，然後搜尋並安裝解決方案中所有專案的 Microsoft.Azure.Mobile.Client.SQLiteStore NuGet 套件。
在 [方案總管] 中，從具有 Portable 名稱的項目開啟TodoItemManager.cs檔案，也就是可攜式類別庫專案，然後取消批注下列預處理器指示詞：
```
 #define OFFLINE_SYNC_ENABLED
```
（選擇性）若要支援 Windows 裝置，請安裝下列其中一個 SQLite 執行時間套件：
- Windows 8.1 執行環境： 安裝 SQLite 適用於 Windows 8.1 的。
- Windows Phone 8.1： 為 Windows Phone 8.1 安裝SQLite。
- 通用 Windows 平臺 安裝 SQLite。
  
  雖然快速入門不包含通用 Windows 專案，但 Xamarin Forms 支援通用 Windows 平臺。
（選擇性）在每個 Windows 應用程式專案中，以滑鼠右鍵按兩下 [參考]>[新增參考...]，展開 [Windows] 資料夾，>[延伸模組]。為 Windows SDK 啟用對應的 SQLite 和適用於 Windows SDK 的 Visual C++ 2013 運行時環境。 SQLite SDK 名稱會隨著每個 Windows 平臺而稍有不同。

檢閱用戶端同步程序代碼

下面是 #if OFFLINE_SYNC_ENABLED 指示詞中教程代碼已包含的內容的簡要概述。離線同步處理功能位於可攜式類別庫專案中TodoItemManager.cs項目檔中。如需此功能的概念概觀，請參閱 Azure Mobile Apps 中的離線數據同步。

必須先初始化本地存儲，才能執行任何數據表作業。本地資料庫在 TodoItemManager 類別的建構函式中使用以下代碼初始化：
```
  var store = new MobileServiceSQLiteStore(OfflineDbPath);
  store.DefineTable<TodoItem>();

  //Initializes the SyncContext using the default IMobileServiceSyncHandler.
  this.client.SyncContext.InitializeAsync(store);

  this.todoTable = client.GetSyncTable<TodoItem>();
```
此程式代碼會使用 MobileServiceSQLiteStore 類別，建立新的本機 SQLite 資料庫。

DefineTable 方法會在本地存儲中建立符合所提供類型欄位的數據表。類型不一定包含遠端資料庫中的所有數據行。可以儲存欄位的子集。

TodoItemManager 中的 [todoTable] 字段是 IMobileServiceSyncTable 類型，而不是 IMobileServiceTable。這個類別會針對所有建立、讀取、更新和刪除（CRUD）資料表作業使用本機資料庫。在您呼叫 PushAsync 於 IMobileServiceSyncContext上時，您可以決定那些變更何時推送至行動應用程式後端。同步上下文透過追蹤並推送用戶端應用程式在呼叫 PushAsync 時修改的所有資料表變更，協助保留資料表的關聯性。

呼叫下列 SyncAsync 方法來與行動應用程式後端同步：

  public async Task SyncAsync()
  {
      ReadOnlyCollection<MobileServiceTableOperationError> syncErrors = null;

      try
      {
          await this.client.SyncContext.PushAsync();

          await this.todoTable.PullAsync(
              "allTodoItems",
              this.todoTable.CreateQuery());
      }
      catch (MobileServicePushFailedException exc)
      {
          if (exc.PushResult != null)
          {
              syncErrors = exc.PushResult.Errors;
          }
      }

      // Simple error/conflict handling.
      if (syncErrors != null)
      {
          foreach (var error in syncErrors)
          {
              if (error.OperationKind == MobileServiceTableOperationKind.Update && error.Result != null)
              {
                  //Update failed, reverting to server's copy.
                  await error.CancelAndUpdateItemAsync(error.Result);
              }
              else
              {
                  // Discard local change.
                  await error.CancelAndDiscardItemAsync();
              }

              Debug.WriteLine(@"Error executing sync operation. Item: {0} ({1}). Operation discarded.",
                  error.TableName, error.Item["id"]);
          }
      }
  }

此範例會使用簡單的錯誤處理搭配預設同步處理程式。實際的應用程式會使用自定義 IMobileServiceSyncHandler 實作來處理各種錯誤，例如網路狀況和伺服器衝突。

離線同步的考量

在範例中，只有在啟動時和要求同步處理時，才會呼叫 SyncAsync 方法。若要在 Android 或 iOS 應用程式中起始同步處理，請下拉項目清單;針對 Windows，請使用 [同步處理] 按鈕。在實際應用中，您也可以在網路狀態變更時進行同步。

針對內容追蹤之暫止本機更新的數據表執行提取時，該提取作業會自動觸發先前的內容推送。在此範例中刷新、添加和完成項目時，您可以省略明確的PushAsync 呼叫。

在提供的程式代碼中，會查詢遠端 TodoItem 資料表中的所有記錄，但也可以藉由傳遞查詢 ID 和查詢條件來篩選記錄，並使用 PushAsync方法進行推送。如需詳細資訊，請參閱 Azure Mobile Apps 的脫機數據同步中的 增量同步 一節。

執行用戶端應用程式

啟用離線同步處理後，請在每個平臺上至少執行一次用戶端應用程式，以填入本地儲存資料庫。稍後，模擬脫機案例，並在應用程式離線時修改本地存儲中的數據。

更新用戶端應用程式的同步處理行為

在本節中，使用一個無效的應用程式 URL 給後端，修改客戶端專案來模擬離線狀況。或者，您可以將裝置移至「飛機模式」，以關閉網路連線。當您新增或變更數據項時，這些變更會保留在本地存儲中，但在重新建立連線之前，不會同步處理至後端數據存放區。

在 [方案總管] 中，從 Portable 項目開啟Constants.cs項目檔，並將 ApplicationURL 的值變更為指向無效的 URL：
```
 public static string ApplicationURL = @"https://your-service.azurewebsites.net/";
```
從 Portable 項目中開啟TodoItemManager.cs檔案，然後將基底 Exception 類別的 catch 新增至 try...catch 區塊中的 SyncAsync。此 catch 區塊會將例外狀況訊息寫入主控台，如下所示：
```
     catch (Exception ex)
     {
         Console.Error.WriteLine(@"Exception: {0}", ex.Message);
     }
```
建置並執行用戶端應用程式。新增一些新項目。請注意，每次嘗試與後端同步處理時，主控台都會記錄例外狀況。這些新項目僅存在於本地商店中，直到可以推送至行動後端。用戶端應用程式的行為就像連線到後端一樣，支援所有建立、讀取、更新、刪除（CRUD）作業。
關閉應用程式，然後重新啟動它，以確認您所建立的新專案會保存至本地存儲。
（選擇性）使用 Visual Studio 檢視您的 Azure SQL Database 數據表，以查看後端資料庫中的數據尚未變更。

在 Visual Studio 中，開啟 [伺服器總管]。前往 azure 中的資料庫->SQL 資料庫。以滑鼠右鍵按下您的資料庫，然後選取 [在 SQL Server 物件總管中開啟] 。現在您可以瀏覽至 SQL 資料庫資料表及其內容。

更新用戶端應用程式以重新連線您的行動後端

在本節中，將應用程式重新連線到行動後端，以模擬應用程式回到在線狀態。當您執行重新整理手勢時，數據會同步至行動後端。

重新開啟Constants.cs。將 applicationURL 更正為指向正確的 URL。
重建並執行客戶端應用程式。啟動之後，應用程式會嘗試與行動應用程式後端同步處理。確認偵錯控制台中未記錄任何例外狀況。
（選擇性）使用 SQL Server 物件總管或 Fiddler 或 Postman等 REST 工具來檢視更新的數據。請注意，後端資料庫與本地存儲之間已同步處理數據。

請注意，資料庫與本地存儲之間的數據已同步處理，並包含您在應用程式中斷連線時新增的專案。

其他資源

Azure Mobile Apps 中的離線數據同步
Azure Mobile Apps .NET SDK HOWTO

共用方式為

啟用 Xamarin.Forms 行動應用程式的離線同步處理

概觀

在快速入門解決方案中啟用離線同步處理功能

檢閱用戶端同步程序代碼

離線同步的考量

執行用戶端應用程式

更新用戶端應用程式的同步處理行為

更新用戶端應用程式以重新連線您的行動後端

其他資源

其他資源