User Tools

Site Tools


notes:uwp:roaming

Roaming in UWP

Members of the ApplicationData class related to data roaming:

public ApplicationDataContainer RoamingSettings { get; }
public StorageFolder RoamingFolder { get; }
public UInt64 RoamingStorageQuota { get; }
public void SignalDataChanged(); 
public event TypedEventHandler<ApplicationData, Object> DataChanged;  

Example: Each app has a quota for roaming application data. Check the ApplicationData.RoamingStorageQuota property to obtain the total size of roaming data allowed:

// Get the maximum size of the data that can be synchronized to the cloud from
// the roaming app data store. The returned value is in KB.
Debug.WriteLine(ApplicationData.Current.RoamingStorageQuota); // 100

Example: Clear roaming settings:

async ApplicationData.Current.ClearAsync(ApplicationDataLocality.Roaming);

Example: Store and read a HighPriority setting. Windows roams the HighPriority setting as quickly as possible. The HighPriority setting is available on Windows Desktop but has no effect on Windows Mobile.

ApplicationDataContainer roamingSettings = ApplicationData.Current.RoamingSettings;
 
// Store a high priority setting, for example, the last page in a book reader app.
roamingSettings.values["HighPriority"] = "82";
 
// Read the high priority setting.
object highPriorityValue = roamingSettings.Values["HighPriority"];

Example: Roam multiple high priority settings:

ApplicationDataContainer roamingSettings = ApplicationData.Current.RoamingSettings;
 
// ApplicationDataCompositeValue must contain no more than 8 KB of data to have it roam quickly.
// If it contains more than 8 KB of data, it will roam as quickly as any other setting.
ApplicationDataCompositeValue compositeValue = new ApplicationDataCompositeValue { 
   { "LastVideoWatched", videoName }, 
   { "LastVideoPosition", videoPosition } 
}; 
roamingSettings.Values["HighPriority"] = compositeValue;

Example: Subscribe to the DataChanged event to receive notifications about changes in the roaming settings data store:

using Windows.Storage;
...
public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.InitializeComponent();
    }
 
    protected override void OnNavigatedTo(NavigationEventArgs args)
    {
        Windows.Storage.ApplicationData.Current.DataChanged += OnDataChanged;
    }
 
    protected override void OnNavigatedFrom(NavigationEventArgs args)
    {
        Windows.Storage.ApplicationData.Current.DataChanged -= OnDataChanged;
    }
 
    // OnDataChanged is invoked whenever roaming data changes.
    private void OnDataChanged(ApplicationData appData, object args)
    {
        Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal,
            () => UpdateFromSettings());
    }
 
    private void UpdateFromSettings()
    {
        ApplicationDataContainer roamingSettings = ApplicationData.Current.RoamingSettings;
 
        // Obtain the setting stored in the TestStr key.
        if (roamingSettings.Values.ContainsKey("TestStr"))
        {
            string str = (string)roamingSettings.Values["TestStr"];
            // ...
        }
 
        // Obtain the setting stored in the TestInt key.
        if (roamingSettings.Values.ContainsKey("TestInt"))
        {
            int n = (int)roamingSettings.Values["TestInt"];
            // ...
        }
    }
 
    // For testing.
    private void TestButton_Click(object sender, RoutedEventArgs e)
    {
        ApplicationDataContainer roamingSettings = ApplicationData.Current.RoamingSettings;
 
        // Change the roaming settings.
        roamingSettings.Values["TestStr"] = "Testing";
        roamingSettings.Values["TestInt"] = 88;
 
        // Signal the change.
        ApplicationData.Current.SignalDataChanged();
    }
}

Notes from the book “WinRT via C#”: When Windows copies a package's roaming data from the cloud onto a user's PC, Windows raises ApplicationData's DataChanged event. If your app registers with this event, it can refresh its new roaming settings and modify its behavior on the fly while the user is interacting with your app. Note that Windows raises this event on a thread pool thread, so you'll have to use a CoreDispatcher if you want to update your app's user interface.

Windows raises the DataChanged event automatically whenever the PC downloads new roaming package data. But your app can raise this event itself by calling ApplicationData's SignalDataChanged method. It may be useful if you need your app to signal a setting change to one of its background tasks or vice versa.

Windows logs roaming-related events in the following system event logs:

  • Applications And Services Logs > Microsoft > Windows > SettingSync
  • Applications And Services Logs > Microsoft > Windows > PackageStateRoaming
notes/uwp/roaming.txt · Last modified: 2017/01/30 by admin