儲存及擷取設定和其他應用程式資料

  • 發行項

應用程式資料是由特定應用程式所建立及管理的可變資料。 其中包含了執行階段狀態、應用程式設定、使用者喜好設定、參考內容 (如字典應用程式中的字典定義) 及其他設定。 應用程式資料與使用者資料不同，後者是使用者在使用應用程式時建立和管理的資料。 使用者資料包括文件或媒體檔案、電子郵件或通訊文字記錄，或保存使用者所建立內容的資料庫記錄。 使用者資料可能同時對多個應用程式有用或有意義。 通常，使用者資料是使用者想要獨立於應用程式之外進行操作或傳輸的資料，例如文件。

關於應用程式資料的重要注意事項：應用程式資料的存留期與應用程式的存留期相關。 如果移除應用程式，所有應用程式資料都會因此遺失。 請勿使用應用程式資料來儲存使用者資料，或使用者可能認為有價值且無可取代的任何內容。 建議使用使用者的資料庫和 Microsoft OneDrive 來儲存此類資訊。 應用程式資料非常適合用來儲存應用程式專用的使用者喜好設定、設定和我的最愛。

應用程式資料類型

應用程式資料有兩種類型：設定和檔案。

設定

請使用設定來儲存使用者喜好設定和應用程式狀態資訊。 應用程式資料 API 可讓您輕鬆建立及擷取設定 (本文稍後會展示一些範例)。

以下是適用於應用程式設定的資料類型：

  • UInt8、Int16、UInt16、Int32、UInt32、Int64、UInt64、Single、Double
  • 布林值
  • Char16、String
  • DateTime、TimeSpan
  • GUID、Point、Size、Rect
  • ApplicationDataCompositeValue：一組必須個別序列化和還原序列化的相關應用程式設定。 使用複合設定，可以輕鬆處理相依設定的不可部分完成更新。 系統會確保複合設定在並行存取和漫遊期間的完整性。 複合設定已針對少量資料進行了最佳化，因此如果將它們用於大型資料集，效能可能會很差。

檔案

請使用檔案來儲存二進位資料，或啟用您自己的自訂序列化類型。

將應用程式資料儲存在應用程式資料存放區中

安裝應用程式後，系統會為其提供專用的個別使用者資料存放區，以供設定和檔案使用。 您不需要知道這些資料的存放位置或方式，因為系統會負責管理實體儲存體，確保這些資料與其他應用程式和其他使用者隔離。 使用者安裝應用程式更新後，系統也會保留這些資料存放區的內容，並在卸載應用程式時全數清除這些資料存放區的內容。

每個應用程式在自己的應用程式資料存放區中都有系統定義的根目錄：一個用於本機檔案、一個用於漫遊檔案，另一個用於暫存檔案。 您的應用程式可以將新檔案和新容器新增至這些根目錄。

本機應用程式資料

本機應用程式資料適合用來儲存需要在不同應用程式工作階段之間保留的資訊，而不適合用來儲存漫遊應用程式資料。 不適用於其他裝置的資料，也應該儲存在這裡。 本機資料沒有一般儲存大小限制。 請使用本機應用程式資料存放區，儲存不需要漫遊的的資料和大型資料集。

擷取本機應用程式資料存放區

您必須先擷取本機應用程式資料存放區，才能讀取或寫入本機應用程式資料。 若要擷取本機應用程式資料存放區，請使用 ApplicationData.LocalSettings 屬性，以 ApplicationDataContainer 物件的形式取得應用程式的本機設定。 請使用 ApplicationData.LocalFolder 屬性來取得 StorageFolder 物件中的檔案。 請使用 ApplicationData.LocalCacheFolder 屬性來取得本機應用程式資料存放區中的資料夾，您可以在其中儲存備份和還原中未包含的檔案。

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

建立和擷取簡單的本機設定

若要建立或寫入設定，請使用 ApplicationDataContainer.Values 屬性來存取我們在上一個步驟中取得的 localSettings 容器中的設定。 本範例會建立名為 exampleSetting 的設定。

// Simple setting

localSettings.Values["exampleSetting"] = "Hello Windows";

若要擷取設定，請使用與建立該設定時所使用的相同 ApplicationDataContainer.Values 屬性。 此範例示範如何擷取剛才建立的設定。

// Simple setting
Object value = localSettings.Values["exampleSetting"];

建立和擷取本機複合值

如要建立或寫入複合值，請建立 ApplicationDataCompositeValue 物件。 此範例會建立名為 exampleCompositeSetting 的複合設定，並將其新增至 localSettings 容器。

// Composite setting

Windows.Storage.ApplicationDataCompositeValue composite = 
    new Windows.Storage.ApplicationDataCompositeValue();
composite["intVal"] = 1;
composite["strVal"] = "string";

localSettings.Values["exampleCompositeSetting"] = composite;

此範例示範如何擷取剛才建立的複合值。

// Composite setting

Windows.Storage.ApplicationDataCompositeValue composite = 
   (Windows.Storage.ApplicationDataCompositeValue)localSettings.Values["exampleCompositeSetting"];

if (composite == null)
{
   // No data
}
else
{
   // Access data in composite["intVal"] and composite["strVal"]
}

建立和讀取本機檔案

若要在本機應用程式資料存放區中建立及更新檔案，請使用檔案 API，例如 Windows.Storage.StorageFolder.CreateFileAsync 和 Windows.Storage.FileIO.WriteTextAsync。 此範例會在 localFolder 容器中建立名為 dataFile.txt 的檔案，並將目前的日期和時間寫入檔案。 CreationCollisionOption 列舉中的 ReplaceExisting 值指出，如果檔案已經存在，則取代該檔案。

async void WriteTimestamp()
{
   Windows.Globalization.DateTimeFormatting.DateTimeFormatter formatter = 
       new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime");

   StorageFile sampleFile = await localFolder.CreateFileAsync("dataFile.txt", 
       CreationCollisionOption.ReplaceExisting);
   await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTimeOffset.Now));
}

若要在本機應用程式資料存放區中開啟和讀取檔案，請使用檔案 API，例如 Windows.Storage.StorageFolder.GetFileAsync、Windows.Storage.StorageFile.GetFileFromApplicationUriAsync 和 Windows.Storage.FileIO.ReadTextAsync。 本範例會開啟在上一個步驟中建立的 dataFile.txt 檔案，並從檔案讀取日期。 如需從各種位置載入檔案資源的詳細資訊，請參閱如何載入檔案資源。

async void ReadTimestamp()
{
   try
   {
      StorageFile sampleFile = await localFolder.GetFileAsync("dataFile.txt");
      String timestamp = await FileIO.ReadTextAsync(sampleFile);
      // Data is contained in timestamp
   }
   catch (Exception)
   {
      // Timestamp not found
   }
}

漫遊資料

警告

從 Windows 11 開始不再支援漫遊資料和設定。 建議的取代是 Azure App Service。 Azure App Service 受到廣泛支援、記載良好、可靠，並支援 iOS、Android 和 Web 等跨平台/跨生態系統案例。

下列文件適用於 Windows 10 1909 和更低版本。

在應用程式中使用漫遊資料，可讓使用者輕鬆地讓應用程式的應用程式資料跨多個裝置保持同步。 如果使用者在多個裝置上安裝了您的應用程式，OS 會保持應用程式資料同步，以減少使用者需要在第二部裝置上為您的應用程式執行的設定工作。 漫遊功能還能讓使用者從上次中斷的位置繼續執行任務 (例如撰寫清單)，甚至是在不同的裝置上。 OS 會在更新時將漫遊資料複製至雲端，並將資料同步至安裝該應用程式的其他裝置。

OS 會限制每個應用程式所能漫遊的應用程式資料大小。 請參閱 ApplicationData.RoamingStorageQuota。 一旦應用程式達到此限制，則其任何應用程式資料都不會複製到雲端，直到其漫遊應用程式資料總量再次低於限制為止。 因此 ，最好只針對使用者喜好設定、連結和小型資料檔案使用漫遊資料。

只要使用者在規定的時間間隔內透過某個裝置存取了應用程式的漫遊資料，該資料就可以在雲端取得。 如果使用者未執行應用程式的時間超過此時間間隔，就會從雲端移除其漫遊資料。 使用者卸載應用程式之後，其漫遊資料將不會自動從雲端移除，而是會保留下來。 如果使用者在時間間隔內重新安裝應用程式，則會從雲端同步漫遊資料。

漫遊資料的可行與禁止事項

請參閱漫遊資料的重要注意事項。

  • 使用者喜好設定和自訂設定、連結和小型資料檔案皆應使用漫遊。 例如，您可以使用漫遊，保留使用者在所有裝置上的背景色彩喜好設定。
  • 使用漫遊功能，讓使用者跨裝置繼續工作。 例如，使用者可以漫遊電子郵件草稿內容、閱讀器應用程式中最近查看的頁面等應用程式資料。
  • 更新應用程式資料以處理 DataChanged 事件。 此事件會在應用程式資料剛從雲端完成同步處理時發生。
  • 請以內容參照 (而非原始資料) 做為漫遊的目標。 例如，與其漫遊線上文章的內容，不如漫遊 URL。
  • 對於具有時間限制的重要設定，請使用與 RoamingSettings 相關聯的 HighPriority 設定。
  • 請勿漫遊特定裝置專用的應用程式資料。 某些資訊僅與本機相關，例如本機檔案資源的路徑名稱。 如果您決定漫遊本機資訊，請確保當該資訊在次要裝置上失效時，可以復原應用程式。
  • 請勿漫遊大型應用程式資料集。 應用程式可以漫遊的應用程式資料量是有限制的；請使用 RoamingStorageQuota 屬性來取得此最大值。 一旦應用程式達到此限制，就無法漫遊任何資料，直到應用程式資料存放區的大小不再超過限制為止。 設計應用程式時，請考慮如何針對較大的資料設下限制，以免超過限制。 例如，如果儲存每個遊戲狀態需要 10 KB，則應用程式可能只允許使用者儲存最多 10 場遊戲。
  • 針對需要即時同步的資料，請勿使用漫遊。 Windows 不保證即時同步；如果使用者離線或使用高延遲的網路，漫遊可能會顯著延遲。 請確保您的 UI 不需要立即同步。
  • 不要漫遊經常變更的資料。 例如，如果您的應用程式追蹤頻繁變化的資訊 (例如歌曲播放秒數)，請勿將其儲存為漫遊應用程式資料。 正確的做法是，選擇變化頻率較低、但仍能提供良好使用者體驗的表示形式，例如目前播放的歌曲。

漫遊的先決條件

請參閱漫遊資料的重要注意事項。

每位使用 Microsoft 帳戶登入裝置的使用者，都可以從漫遊應用程式資料中受益。 但是，使用者和群組原則管理員可以隨時關閉裝置上的漫遊應用程式資料。 如果使用者選擇不使用 Microsoft 帳戶或停用漫遊資料功能，還是可以使用您的應用程式，但是應用程式資料將是每個裝置的本機資料。

只有當使用者將裝置設定為「受信任」時，儲存在 PasswordVault 中的資料才會轉換。 如果裝置不受信任，此保存庫中的資料將無法漫遊。

衝突解決功能

請參閱漫遊資料的重要注意事項。

漫遊應用程式資料不適合一次在多個裝置上同時使用。 如果因為兩個裝置上的特定資料單元發生變更，導致同步處理期間發生衝突，系統一律會優先使用最後寫入的值。 這可確保應用程式使用最新的資訊。 如果資料單元是設定組合，則在設定單元層級上仍會發生衝突解決，這表示系統將會同步處理最近變更的組合。

何時寫入資料

請參閱漫遊資料的重要注意事項。

資料應根據設定的預期存留期，在不同的時間寫入。 不常變更或變更緩慢的應用程式資料應立即寫入。 經常變更的應用程式資料則應定期寫入 (例如每 5 分鐘寫入一次)，並在應用程式暫停時寫入。 例如，每當新歌曲開始播放時，音樂應用程式可以立即寫入「目前歌曲」設定；但歌曲中的實際位置則應只在應用程式暫停時寫入。

過度使用保護

請參閱漫遊資料的重要注意事項。

系統設有各種保護機制，以避免不當使用資源。 如果應用程式資料未按預期轉換，代表裝置可能已暫時受到限制。 只要等待一段時間，這種情況通常就會自動解決，無需採取任何動作。

版本控制

請參閱漫遊資料的重要注意事項。

應用程式資料可以利用版本設定，從一種資料結構升級到另一種資料結構。 與應用程式版本不同，版本號碼可以隨意設定。 儘管不是強制規定，但強烈建議您使用遞增的版本號碼，因為如果您嘗試轉換較新的資料、卻使用較低資料版本號碼來代表該資料，可能會發生非預期的複雜情況 (包括資料遺失)。

應用程式資料只會在版本號碼相同的已安裝應用程式之間漫遊。 例如，執行第 2 版的裝置會彼此轉換資料，而執行第 3 版的裝置也會執行相同的動作，但執行第 2 版的裝置與執行第 3 版的裝置之間不會發生漫遊。 如果您安裝的新應用程式在其他裝置上使用了不同的版本號碼，則新安裝的應用程式將會同步版本號碼最高的應用程式資料。

測試和工具

請參閱漫遊資料的重要注意事項。

開發人員可以鎖定裝置，以觸發漫遊應用程式資料的同步處理。 如果應用程式資料似乎未在特定時間範圍內轉換，請檢查以下項目並確保：

  • 漫遊資料並未超過大小上限 (如需詳細資訊，請參閱 RoamingStorageQuota)。
  • 檔案已正確關閉並釋放。
  • 至少有兩個裝置執行相同版本的應用程式。

註冊以接收漫遊資料變更通知

請參閱漫遊資料的重要注意事項。

若要使用漫遊應用程式資料，您必須註冊漫遊資料變更，並擷取漫遊資料容器，以便讀取和寫入設定。

  1. 註冊以接收漫遊資料變更通知。

    DataChanged 事件會在漫遊資料變更時通知您。 本範例會將 DataChangeHandler 設定為漫遊資料變更的處理常式。

void InitHandlers()
    {
       Windows.Storage.ApplicationData.Current.DataChanged += 
          new TypedEventHandler<ApplicationData, object>(DataChangeHandler);
    }

    void DataChangeHandler(Windows.Storage.ApplicationData appData, object o)
    {
       // TODO: Refresh your data
    }

  1. 取得應用程式的設定和檔案容器。

    使用 ApplicationData.RoamingSettings 屬性來取得設定，並使用 ApplicationData.RoamingFolder 屬性來取得檔案。

Windows.Storage.ApplicationDataContainer roamingSettings = 
        Windows.Storage.ApplicationData.Current.RoamingSettings;
    Windows.Storage.StorageFolder roamingFolder = 
        Windows.Storage.ApplicationData.Current.RoamingFolder;

建立和擷取漫遊設定

請參閱漫遊資料的重要注意事項。

使用 ApplicationDataContainer.Values 屬性來存取我們在上一節中取得的 roamingSettings 容器中的設定。 此範例會建立名為 exampleSetting 的簡單設定，以及名為 composite 的複合值。

// Simple setting

roamingSettings.Values["exampleSetting"] = "Hello World";
// High Priority setting, for example, last page position in book reader app
roamingSettings.values["HighPriority"] = "65";

// Composite setting

Windows.Storage.ApplicationDataCompositeValue composite = 
    new Windows.Storage.ApplicationDataCompositeValue();
composite["intVal"] = 1;
composite["strVal"] = "string";

roamingSettings.Values["exampleCompositeSetting"] = composite;

此範例會擷取我們剛才建立的設定。

// Simple setting

Object value = roamingSettings.Values["exampleSetting"];

// Composite setting

Windows.Storage.ApplicationDataCompositeValue composite = 
   (Windows.Storage.ApplicationDataCompositeValue)roamingSettings.Values["exampleCompositeSetting"];

if (composite == null)
{
   // No data
}
else
{
   // Access data in composite["intVal"] and composite["strVal"]
}

建立和擷取漫遊檔案

請參閱漫遊資料的重要注意事項。

若要在漫遊應用程式資料存放區中建立及更新檔案，請使用檔案 API，例如 Windows.Storage.StorageFolder.CreateFileAsync 和 Windows.Storage.FileIO.WriteTextAsync。 此範例會在 roamingFolder 容器中建立名為 dataFile.txt 的檔案，並將目前的日期和時間寫入檔案。 CreationCollisionOption 列舉中的 ReplaceExisting 值指出，如果檔案已經存在，則取代該檔案。

async void WriteTimestamp()
{
   Windows.Globalization.DateTimeFormatting.DateTimeFormatter formatter = 
       new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime");

   StorageFile sampleFile = await roamingFolder.CreateFileAsync("dataFile.txt", 
       CreationCollisionOption.ReplaceExisting);
   await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTimeOffset.Now));
}

若要在漫遊應用程式資料存放區中開啟和讀取檔案，請使用檔案 API，例如 Windows.Storage.StorageFolder.GetFileAsync、Windows.Storage.StorageFile.GetFileFromApplicationUriAsync 和 Windows.Storage.FileIO.ReadTextAsync。 本範例會開啟在上一節中建立的 dataFile.txt 檔案，並從檔案讀取日期。 如需從各種位置載入檔案資源的詳細資訊，請參閱如何載入檔案資源。

async void ReadTimestamp()
{
   try
   {
      StorageFile sampleFile = await roamingFolder.GetFileAsync("dataFile.txt");
      String timestamp = await FileIO.ReadTextAsync(sampleFile);
      // Data is contained in timestamp
   }
   catch (Exception)
   {
      // Timestamp not found
   }
}

暫存應用程式資料

暫存應用程式資料存放區的運作方式就像快取一樣。 暫存應用程式資料存放區中的檔案不會漫遊，而且可以隨時移除。 系統維護工作可隨時自動刪除儲存在此位置的資料。 使用者也可以使用磁碟清理，清除暫存資料存放區中的檔案。 暫存應用程式資料可用來儲存應用程式工作階段期間的暫存資訊。 系統可能會在需要時回收已使用的空間，因此無法保證這些資料在應用程式工作階段結束後仍然存在。 此位置可透過 temporaryFolder 屬性取得。

擷取暫存資料容器

請使用 ApplicationData.TemporaryFolder 屬性來取得檔案。 後續步驟會使用這個步驟中的 temporaryFolder 變數。

Windows.Storage.StorageFolder temporaryFolder = ApplicationData.Current.TemporaryFolder;

建立和讀取暫存檔案

若要在暫存應用程式資料存放區中建立及更新檔案，請使用檔案 API，例如 Windows.Storage.StorageFolder.CreateFileAsync 和 Windows.Storage.FileIO.WriteTextAsync。 此範例會在 temporaryFolder 容器中建立名為 dataFile.txt 的檔案，並將目前的日期和時間寫入檔案。 CreationCollisionOption 列舉中的 ReplaceExisting 值指出，如果檔案已經存在，則取代該檔案。

async void WriteTimestamp()
{
   Windows.Globalization.DateTimeFormatting.DateTimeFormatter formatter = 
       new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime");

   StorageFile sampleFile = await temporaryFolder.CreateFileAsync("dataFile.txt", 
       CreateCollisionOption.ReplaceExisting);
   await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTimeOffset.Now));
}

若要在暫存應用程式資料存放區中開啟和讀取檔案，請使用檔案 API，例如 Windows.Storage.StorageFolder.GetFileAsync、Windows.Storage.StorageFile.GetFileFromApplicationUriAsync 和 Windows.Storage.FileIO.ReadTextAsync。 本範例會開啟在上一個步驟中建立的 dataFile.txt 檔案，並從檔案讀取日期。 如需從各種位置載入檔案資源的詳細資訊，請參閱如何載入檔案資源。

async void ReadTimestamp()
{
   try
   {
      StorageFile sampleFile = await temporaryFolder.GetFileAsync("dataFile.txt");
      String timestamp = await FileIO.ReadTextAsync(sampleFile);
      // Data is contained in timestamp
   }
   catch (Exception)
   {
      // Timestamp not found
   }
}

使用容器組織應用程式資料

為了協助您組織應用程式資料設定和檔案，您可以建立容器 (以 ApplicationDataContainer 物件表示)，而不是直接使用目錄。 您可以在本機、漫遊和暫存應用程式資料存放區中新增容器。 容器的巢狀結構最多可以有 32 個層級。

若要建立設定容器，請叫用 ApplicationDataContainer.CreateContainer 方法。 此範例會建立名為 exampleContainer 的本機設定容器，並新增名為 exampleSetting 的設定。 ApplicationDataCreateDisposition 列舉中的 Always 值表示如果容器不存在，就會建立容器。

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Setting in a container
Windows.Storage.ApplicationDataContainer container = 
   localSettings.CreateContainer("exampleContainer", Windows.Storage.ApplicationDataCreateDisposition.Always);

if (localSettings.Containers.ContainsKey("exampleContainer"))
{
   localSettings.Containers["exampleContainer"].Values["exampleSetting"] = "Hello Windows";
}

刪除應用程式設定和容器

若要刪除應用程式不再需要的簡單設定，請使用 ApplicationDataContainerSettings.Remove 方法。 此範例會刪除稍早建立的 exampleSetting 本機設定。

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Delete simple setting

localSettings.Values.Remove("exampleSetting");

如要刪除複合設定，請使用 ApplicationDataCompositeValue.Remove 方法。 此範例會刪除我們在先前範例中建立的本機 exampleCompositeSetting 複合設定。

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Delete composite setting

localSettings.Values.Remove("exampleCompositeSetting");

若要刪除容器，請叫用 ApplicationDataContainer.DeleteContainer 方法。 此範例會刪除稍早建立的本機 exampleContainer 設定容器。

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Delete container

localSettings.DeleteContainer("exampleContainer");

設定您的應用程式資料版本

您可以選擇為應用程式設定應用程式資料版本。 如此一來，您就能建立下一個版本的應用程式，並變更應用程式資料的格式，而不會產生與前一版應用程式的相容性問題。 應用程式會檢查資料存放區中的應用程式資料版本，如果版本低於應用程式期望的版本，則應用程式應將應用程式資料更新為新的格式，並更新版本。 如需詳細資訊，請參閱 Application.Version 屬性和 ApplicationData.SetVersionAsync 方法。