在 UWP 應用程式中儲存和載入設定

發行項
10/05/2023

本主題涵蓋您需要了解在通用 Windows 平台 (UWP) 應用程式中開始設定載入與儲存、設定的資訊。介紹了主要 API，並提供連結有助於您了解更多資訊。

使用設定以記住應用程式的使用者可自訂層面。例如，新聞閱讀程式可使用應用程式設定儲存要顯示哪一則新聞來源，以及要用於閱讀文章所使用的字型。

我們將查看程式碼來儲存和載入應用程式設定。

您需要知道的事項

使用應用程式設定來儲存設定資料，例如使用者的喜好設定和應用程式狀態。

設定可以使用下列的資料類型：整數、加倍、浮點數、字元、字串、點、DateTimes，及更多。您也可以儲存 ApplicationDataCompositeValue 類別的執行個體，有多個應視為一個單位的設定時，很實用。例如，您的應用程式 \[讀取\] 窗格中顯示文字的字型名稱與點大小，應該以單一單位來儲存/還原。這可防止一個設定因為平行存取而與另一個設定不同步，例如主要程式與背景工作之間的存取。

以下是您必須知道的主要 API 來儲存或載入應用程式設定：

Windows.Storage.ApplicationData.Current.LocalSettings 從本機應用程式資料存放區取得應用程式設定容器。此處儲存的設定會保留在裝置上。
Windows.Storage.ApplicationData.Current.RoamingSettings 從漫遊應用程式資料存放區取得應用程式設定容器。儲存在這裡的設定不再漫遊 (從 Windows 11 起)，但設定存放區仍可供使用。 RoamingSettings 的建議取代項目是 Azure App Service。 Azure App Service 受到廣泛支援、記載良好、可靠，並支援 iOS、Android 和 Web 等跨平台/跨生態系統案例。
Windows.Storage.ApplicationDataContainer 是一種容器，其表示應用程式設定為索引鍵/值組。使用這個類別來建立和擷取設定值。
Windows.Storage.ApplicationDataCompositeValue 代表應以單位序列化的多個應用程式設定。當一個設定不應該獨立更新時，這非常有用。

儲存應用程式設定

在此簡介中，我們將著重於兩個簡單的案例：儲存和載入簡單的應用程式設定，以及儲存和載入複合字型/字型大小設定。

ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;

// Save a setting locally on the device
localSettings.Values["test setting"] = "a device specific setting";

// Save a composite setting locally on the device
Windows.Storage.ApplicationDataCompositeValue composite = new Windows.Storage.ApplicationDataCompositeValue();
composite["Font"] = "Calibri";
composite["FontSize"] = 11;
localSettings.Values["FontInfo"] = composite;

透過使用 Windows.Storage.ApplicationData.Current.LocalSettings 優先取得本機設定資料存放區的 ApplicationDataContainer 儲存設定。您指派給此執行個體的索引鍵/值字典組會儲存在本機裝置設定資料存放區中。

上述的程式碼片段中，ApplicationDataCompositeValue 儲存多個索引鍵/值組。當您有多個應該不會彼此同步處理的設定時，複合值會很實用。當您儲存 ApplicationDataCompositeValue 時，以一個單位儲存與載入這些值，或自動完成。如此一來，相關的設定就不會同步。

載入應用程式設定

ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;

// load a setting that is local to the device
String localValue = localSettings.Values["test setting"] as string;

// load a composite setting
Windows.Storage.ApplicationDataCompositeValue composite = (ApplicationDataCompositeValue)localSettings.Values["FontInfo"];
if (composite != null)
{
    String fontName = composite["Font"] as string;
    int fontSize = (int)composite["FontSize"];
}

透過使用 Windows.Storage.ApplicationData.Current.LocalSettings 優先取得本機設定資料存放區的 ApplicationDataContainer 執行個體來載入設定。然後用來擷取索引鍵/值組。如果資料不存在，您將取得 Null 物件。在 C# 中，這表示如果設定不存在，localValue 將為 null。

遵循類似的模式載入複合設定。從本機設定資料存放區存取機碼值組。如果資料不存在，您會收到 null ApplicationDataContainer。這便是在上述範例程式碼中有 if (composite != null) 檢查的原因。

實用的 API 和文件

以下是 API 的快速摘要，以及其他實用的文件，有助於您開始儲存與載入應用程式設定。

實用的 API

API	描述
ApplicationData.LocalSettings	從本機應用程式資料存放區中取得應用程式設定容器。
ApplicationData.RoamingSettings	從漫遊應用程式資料存放區中取得應用程式設定容器。
ApplicationDataContainer	應用程式設定的容器，支援建立、移除、列舉，與周遊容器階層。
Windows.UI.ApplicationSettings 命名空間	提供您會用來定義應用程式設定的類別，其顯示在 Windows 殼層的設定窗格中。

實用的文件

主題	說明
應用程式設定的指導方針	描述建立和顯示應用程式設定的最佳做法。
儲存及擷取設定和其他應用程式資料	用於儲存和擷取設定的逐步解說。

實用的程式碼範例

程式碼範例	描述
應用程式資料範例	案例 2-4 著重於設定

共用方式為