Quickstart: Roaming app data (XAML)

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Learn how to store and retrieve settings and files from the roaming app data store. For info about the roaming app data store and why you'd want to use it, see Roaming app data.

Roadmap: How does this topic relate to others? See:

• Roadmap for Windows Runtime apps using C# or Visual Basic
• Roadmap for Windows Runtime apps using C++

Register to receive notification when roaming data changes

Register for the DataChanged event. This example sets DataChangeHandler as the handler for roaming data changes.

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

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

Private Sub InitHandlers()
    AddHandler Windows.Storage.ApplicationData.Current.DataChanged, AddressOf DataChangeHandler
End Sub

Private Sub DataChangeHandler(ByVal appData As Windows.Storage.ApplicationData, ByVal o As Object)
    ' TODO: Refresh your data
End Sub

void MainPage::InitHandlers()
{
   Windows::Storage::ApplicationData::Current->DataChanged += 
      ref new TypedEventHandler<Windows::Storage::ApplicationData^, Object^>
      (this, &MainPage::DataChangeHandler);
}

void MainPage::DataChangeHandler(Windows::Storage::ApplicationData^ appData, Object^)
{
   // TODO: Refresh your data
}

Get the containers for the app's settings and files

Use the ApplicationData.RoamingSettings property to get the settings and the ApplicationData.RoamingFolder property to get the files.

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

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

ApplicationDataContainer^ roamingSettings = ApplicationData::Current->RoamingSettings;
StorageFolder^ roamingFolder = ApplicationData::Current->RoamingFolder;

Write data to a setting

Use the ApplicationDataContainer.Values property to access the settings in the roamingSettings container we got in the previous section. This example creates a setting named exampleSetting.

// Simple setting

roamingSettings.Values["exampleSetting"] = "Hello World";

' Simple setting
roamingSettings.Values("exampleSetting") = "Hello World";

// Simple setting

auto values = roamingSettings->Values;
values->Insert("exampleSetting", dynamic_cast<PropertyValue^>(PropertyValue::CreateString("Hello World")));

An ApplicationDataCompositeValue object contains settings that must be accessed atomically. This example creates a composite setting named exampleCompositeSetting and adds it to the roamingSettings container.

// Composite setting

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

roamingSettings.Values["exampleCompositeSetting"] = composite;

' Composite setting

Dim composite As New Windows.Storage.ApplicationDataCompositeValue
composite("intVal") = 1
composite("strVal") = "string";

roamingSettings.Values("exampleCompositeSetting") = composite

// Composite setting

ApplicationDataCompositeValue^ composite = ref new ApplicationDataCompositeValue();
composite->Insert("intVal", dynamic_cast<PropertyValue^>(PropertyValue::CreateInt32(1)));
composite->Insert("strVal", dynamic_cast<PropertyValue^>(PropertyValue::CreateString("string")));

auto values = roamingSettings->Values;
values->Insert("exampleCompositeSetting", composite);

Call the ApplicationDataContainer.CreateContainer method to create a settings container. This example creates a settings container named exampleContainer and adds a setting named exampleSetting. The Always value from the ApplicationDataCreateDisposition enumeration indicates that the container is created if it doesn't already exist.

// Setting in a container

Windows.Storage.ApplicationDataContainer container = 
   roamingSettings.CreateContainer("exampleContainer", Windows.Storage.ApplicationDataCreateDisposition.Always);

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

' Setting in a container

Dim container As Windows.Storage.ApplicationDataContainer = 
   roamingSettings.CreateContainer("exampleContainer", Windows.Storage.ApplicationDataCreateDisposition.Always)

If roamingSettings.Containers.ContainsKey("exampleContainer") Then
    roamingSettings.Containers("exampleContainer").Values("exampleSetting") = "Hello World"
End If

// Setting in a container

ApplicationDataContainer^ container = 
   roamingSettings->CreateContainer("exampleContainer", ApplicationDataCreateDisposition::Always);

if (roamingSettings>Containers->HasKey("exampleContainer"))
{
   auto values = roamingSettings>Containers->Lookup("exampleContainer")->Values;
   values->Insert("exampleSetting", "Hello World");
}

Read data from a setting

Use the ApplicationDataContainer.Values property to access the exampleSetting setting in the roamingSettings container.

// Simple setting

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

' Simple setting

Dim value As Object = roamingSettings.Values("exampleSetting")

// Simple setting

auto values = roamingSettings->Values;
String^ value = safe_cast<String^>(roamingSettings->Values->Lookup("exampleSetting"));

Use the ApplicationDataContainer.Values property to access the exampleCompositeSetting setting in the roamingSettings container.

// 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"]
}

' Composite setting

Dim composite As Windows.Storage.ApplicationDataCompositeValue = 
   CType(roamingSettings.Values("exampleCompositeSetting"), Windows.Storage.ApplicationDataCompositeValue)

If composite Is Nothing Then
   ' No data
Else
   ' Access data in composite("intVal") and composite("strVal")
End If

// Composite setting

ApplicationDataCompositeValue^ composite = 
   safe_cast<ApplicationDataCompositeValue^>(roamingSettings->Values->Lookup("exampleCompositeSetting"));

if (composite == nullptr)
{
   // No data
}
else
{
   int one = safe_cast<IPropertyValue^>(composite->Lookup("intVal"))->GetInt32();
   String^ hello = safe_cast<String^>(composite->Lookup("strVal"));
}

Use the ApplicationDataContainer.Values property to access the exampleSetting setting in the exampleContainer container.

// Setting in a container

bool hasContainer = roamingSettings.Containers.ContainsKey("exampleContainer");
bool hasSetting = false;

if (hasContainer)
{
   hasSetting = roamingSettings.Containers["exampleContainer"].Values.ContainsKey("exampleSetting");
}

' Setting in a container

Dim hasContainer As Boolean = roamingSettings.Containers.ContainsKey("exampleContainer")
Dim hasSetting As Boolean = False

If hasContainer Then
    hasSetting = roamingSettings.Containers("exampleContainer").Values.ContainsKey("exampleSetting")
End If

// Setting in a container

bool hasContainer = roamingSettings->Containers->HasKey("exampleContainer");
bool hasSetting = false;

if (hasContainer)
{
   auto values = roamingSettings->Containers->Lookup("exampleContainer")->Values;
   hasSetting = values->HasKey("exampleSetting");
}

Write data to a file

Use the file APIs, such as Windows.Storage.StorageFolder.CreateFileAsync and Windows.Storage.FileIO.WriteTextAsync, to create and update a file in the roaming app data store. This example creates a file named dataFile.txt in the roamingFolder container and writes the current date and time to the file. The ReplaceExisting value from the CreationCollisionOption enumeration indicates to replace the file if it already exists.

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(DateTime.Now));
}

Imports Windows.Globalization.DateTimeFormatting

Private Async Sub WriteTimestamp()
   Dim formatter As DateTimeFormatter = New DateTimeFormatter("longtime")

   Dim sampleFile As StorageFile = Await roamingFolder.CreateFileAsync("dataFile.txt", 
       CreationCollisionOption.ReplaceExisting)
   Await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTime.Now));
End Sub

void MainPage::WriteTimestamp()
{
   concurrency::task<StorageFile^> fileOperation = 
       roamingFolder->CreateFileAsync("dataFile.txt", CreationCollisionOption::ReplaceExisting);
   fileOperation.then([this](StorageFile^ sampleFile)
   {
      auto calendar = ref new Calendar;
      auto now = calendar->ToDateTime();
      auto formatter = ref new Windows::Globalization::DateTimeFormatting::DateTimeFormatter("longtime");

      return FileIO::WriteTextAsync(sampleFile, formatter->Format(now));
   }).then([this](task<void> previousOperation) {
      try {
         previousOperation.get();
      } catch (Platform::Exception^) {
         // Timestamp not written
      }
   });
}

Read data from a file

Use the file APIs, such as Windows.Storage.StorageFolder.GetFileAsync, Windows.Storage.StorageFile.GetFileFromApplicationUriAsync, and Windows.Storage.FileIO.ReadTextAsync, to open and read a file in the roaming app data store. This example opens the dataFile.txt file created in the previous section and reads the date from the file. For details on loading file resources from various locations, see How to load file resources.

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
   }
}

Private Async Function ReadTimestamp() As Task
   Try
      Dim sampleFile As StorageFile = Await roamingFolder.GetFileAsync("dataFile.txt")
      Dim timestamp As string = Await FileIO.ReadTtextAsync(sampleFile)
      ' Data is contained in timestamp
   Catch e1 As Exception
      ' Timestamp not found
   End Try
End Function

void MainPage::ReadTimestamp()
{
   concurrency::task<StorageFile^> getFileOperation(roamingFolder->GetFileAsync("dataFile.txt"));
   getFileOperation.then([this](StorageFile^ file)
   {
      return FileIO::ReadTextAsync(file);
   }).then([this](concurrency::task<String^> previousOperation) {
      String^ timestamp;
 
      try {
         // Data is contained in timestamp
         timestamp = previousOperation.get();
      } catch (...) {
         // Timestamp not found
      }
   });
}

Delete settings when finished with them

Call the ApplicationDataContainerSettings.Remove method to delete the exampleSetting setting from the roamingSettings container when you have finished with it.

// Delete simple setting

roamingSettings.Values.Remove("exampleSetting");

' Delete simple setting

roamingSettings.Values.Remove("exampleSetting")

// Delete simple setting

auto values = roamingSettings->Values;
values->Remove("exampleSetting");

Call the ApplicationDataCompositeValue.Remove method to delete the exampleCompositeSetting composite setting from the roamingSettings container when you have finished with it.

// Delete composite setting

roamingSettings.Values.Remove("exampleCompositeSetting");

' Delete composite setting

roamingSettings.Values.Remove("exampleCompositeSetting")

// Delete composite setting

Call the ApplicationDataContainer.DeleteContainer method to delete the exampleContainer settings container when you have finished with it.

// Delete container

roamingSettings.DeleteContainer("exampleContainer");

' Delete container

roamingSettings.DeleteContainer("exampleContainer")

// Delete container

roamingSettings->DeleteContainer("exampleContainer");

Roam data across different types of devices

If you publish two versions of your app - a version for Windows Store and a version for Windows Phone Store - you can roam app data across the apps running on the two different types of devices. To roam data across different versions of your app on different types of devices, assign the same Package Family Name (PFN) to each version of the app.

For more info, see How to roam data between a Windows Store app and a Windows Phone Store app.

Remarks

Each app has a quota for roaming app data. Check the ApplicationData.RoamingStorageQuota property to determine the total size of roaming data allowed. If your roaming data exceeds the quota, it won’t roam until its size is less than the quota again.

Related topics

Tasks

How to load file resources

Quickstart: Local app data

Quickstart: Temporary app data

Conceptual

Accessing app data with the Windows Runtime

Guidelines

Guidelines for roaming app data

Reference

Windows.Storage.ApplicationData

Windows.Storage.ApplicationDataCompositeValue

Windows.Storage.ApplicationDataContainer

Windows.Storage.ApplicationDataContainerSettings

Samples

Application data sample