Quickstart: Roaming app data (HTML)

[ 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 about storing and retrieving 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.

Register to receive notification when roaming data changes

This example sets datachangeHandler as the handler for roaming data changes.

var applicationData = Windows.Storage.ApplicationData.current;
 
function initialize() 
{
    applicationData.addEventListener("datachanged", datachangeHandler);
}

function dataChangeHandler(eventArgs)
{
    // 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.

var roamingSettings = applicationData.roamingSettings;
var roamingFolder = applicationData.roamingFolder;

The next steps use the roamingSettings and roamingFolder variables from this step.

Write data to a setting

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

// Simple setting

roamingSettings.values["exampleSetting"] = "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

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

roamingSettings.values["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.

After changing a setting in the roaming app data store, the operating system sends the datachanged event.

// Setting in a container

var container = roamingSettings.createContainer("exampleContainer", 
                                                Windows.Storage.ApplicationDataCreateDisposition.Always);

if (roamingSettings.containers.hasKey("exampleContainer"))
{
    roamingSettings.containers.lookup("exampleContainer").values["exampleSetting"] = "Hello World";
}

Read data from a setting

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

// Simple setting

var value = roamingSettings.values["exampleSetting"];
        
if (!value)
{
    // No data
}
else
{
    // Access data in value
}

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

// Composite setting

var composite = roamingSettings.values["exampleCompositeSetting"];

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

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

// Setting in a container

var hasContainer = roamingSettings.containers.hasKey("exampleContainer");

if (hasContainer)
{
    // Access data in roamingSettings.containers.lookup("exampleContainer").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.

function writeTimestamp() {
   roamingFolder.createFileAsync("dataFile.txt", Windows.Storage.CreationCollisionOption.replaceExisting)
      .then(function (sampleFile) {
         var formatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime");
         var timestamp = formatter.format(new Date());

         return Windows.Storage.FileIO.writeTextAsync(sampleFile, timestamp);
      }).done(function () {      
      });
}

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 step and reads the date from the file. The openIfExists value from the CreationCollisionOption enumeration indicates that the file must exist. For details on loading file resources from various locations, see How to load file resources.

function readTimestamp() {
   roamingFolder.getFileAsync("dataFile.txt")
      .then(function (sampleFile) {
         return Windows.Storage.FileIO.readTextAsync(sampleFile);
      }).done(function (timestamp) {
         // Data is contained in timestamp
      }, function () {
         // 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.

// Simple setting

roamingSettings.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");

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

// Delete container

roamingSettings.deleteContainer("exampleContainer");

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

Task

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