Application Data and Settings

Application Data and Preferences

To store persistent application data and user settings, you can utilize the Windows.Storage.ApplicationData class in Uno Platform.

Legend

  • ✔ Supported
Picker WinUI WebAssembly Android iOS macOS Skia Desktop
LocalFolder ✔ ✔ ✔ ✔ ✔ ✔
RoamingFolder ✔ ✔ ✔ ✔ ✔ ✔
LocalCacheFolder ✔ ✔ ✔ ✔ ✔ ✔
TemporaryFolder ✔ ✔ ✔ ✔ ✔ ✔
LocalSettings ✔ ✔ ✔ ✔ ✔ ✔
RoamingSettings ✔ ✔ ✔ ✔ ✔ ✔

Please note that RoamingFolder and RoamingSettings are not roamed automatically across devices, they only provide a logical separation between data that you intend to roam and that you intend to keep local.

Important

Windows Packaging Requirement: On Windows, ApplicationData functionality requires your app to be configured as a Packaged app. The default project configuration uses Unpackaged mode to enable better Hot Reload support (both C# and XAML), but this will prevent ApplicationData from working. If you need ApplicationData functionality on Windows, you'll need to switch your project to Packaged mode. See the Windows publishing documentation for more details on packaging configuration.

Storing application data

There are several folders where persistent application data can be stored:

  • LocalFolder/RoamingFolder - general-use application files
  • TemporaryFolder - files with limited lifetime
  • LocalCacheFolder - cached files retrieved from external services

In the case of TemporaryFolder and LocalCacheFolder it is crucial to remember that the user or operating system may purge files stored in these locations to reclaim storage space. To store persistent files prefer the LocalFolder or RoamingFolder.

The following example shows how you can create a file in LocalFolder and then read the contents back:

StorageFolder folder = ApplicationData.Current.LocalFolder;

// Create a file in the root of LocalFolder.
StorageFile file = await folder.CreateFileAsync("file.txt", CreationCollisionOption.ReplaceExisting);

// Write text in the newly created file.
await FileIO.WriteTextAsync(file, "Hello, Uno Platform!");

// Read the text from file.
string text = await FileIO.ReadTextAsync(file);

Storing settings

The LocalSettings and RoamingSettings properties provide access to simple key-value containers that allow storage of lightweight user and application preferences. The values stored in settings should be simple serializable types. To store more complex data structures, it is preferred to serialize them first into a string (for example using a JSON serializer).

ApplicationDataContainer localSettings = ApplicationData.Current.LocalSettings;

// Save a setting.
localSettings.Values["name"] = "Martin";

// Read a setting.
string value = (string)localSettings.Values["name"];

Initialization considerations

ApplicationData APIs cannot be used before the App instance is constructed (i.e., before the instance constructor runs). It is possible to start using them in the App constructor, or the Application.OnLaunched method.

Data location on Skia Desktop

In the case of Skia Desktop targets, the data are stored in application- and user-specific locations on the hard drive. The default path to the various folders depends on the runtime operating system.

Windows

  • LocalFolder - C:\Users\UserName>\AppData\Local\<Publisher>\<ApplicationName>\LocalState
  • RoamingFolder - C:\Users\<UserName>\AppData\Local\<Publisher>\<ApplicationName>\RoamingState
  • LocalCacheFolder - C:\Users\<UserName>\AppData\Local\<Publisher>\<ApplicationName>\LocalCache
  • TemporaryFolder - C:\Users\<UserName>\AppData\Local\Temp\<Publisher>\<ApplicationName>\TempState
  • LocalSettings - C:\Users\<UserName>\AppData\Local\<Publisher>\<ApplicationName>\Settings\Local.dat
  • RoamingSettings - C:\Users\<UserName>\AppData\Local\<Publisher>\<ApplicationName>\Settings\Roaming.dat

Unix-based systems

  • LocalFolder - /home/<UserName>/.local/share/<Publisher>/<ApplicationName>/LocalState
  • RoamingFolder - /home/<UserName>/.local/share/<Publisher>/<ApplicationName>/RoamingState
  • TemporaryFolder - /tmp/<Publisher>/<ApplicationName>/TempState
  • LocalCache - /home/<UserName>/.cache/<Publisher>/<ApplicationName>/LocalCache
  • LocalSettings - /home/<UserName>/.local/share/<Publisher>/<ApplicationName>/Settings/Local.dat
  • RoamingSettings - /home/<UserName>/.local/share/<Publisher>/<ApplicationName>/Settings/Roaming.dat

Where <UserName> is the name of the currently logged-in user and <Publisher> and <ApplicationName> are values coming from the <Identity> node of the Package.appxmanifest (note that the publisher value is prefixed by CN= in the manifest, but this is excluded from the folder name).

The default paths above can be overridden using the following feature flags:

  • WinRTFeatureConfiguration.ApplicationData.TemporaryFolderPathOverride - affects TemporaryFolder location
  • WinRTFeatureConfiguration.ApplicationData.LocalCacheFolderPathOverride - affects LocalCacheFolder location
  • WinRTFeatureConfiguration.ApplicationData.ApplicationDataPathOverride - affects LocalFolder, RoamingFolder, LocalCacheFolder, LocalSettings and RoamingSettings

These properties need to be set before the application is initialized. The best place for this is Program.cs, before the UnoPlatformHostBuilder instance is created.

If you intend to support both Windows and Unix-based systems for the Desktop target, make the path conditional utilizing RuntimeInformation.IsOSPlatform(OSPlatform.Windows).

Settings storage on iOS and tvOS

On iOS and tvOS, LocalSettings and RoamingSettings are backed by a dedicated NSUserDefaults suite named UnoApplicationData, persisted as Library/Preferences/UnoApplicationData.plist inside the application sandbox. Both settings containers share this single backing store.

Only the keys stored in that suite are visible through ApplicationData. The keys the OS and Apple frameworks keep in NSUserDefaults.StandardUserDefaults, and any your own native code writes there, are never enumerated by Values.Keys nor removed by Values.Clear().

If you need to access the stored values from native or interop code, open the suite explicitly:

var unoDefaults = new NSUserDefaults("UnoApplicationData", NSUserDefaultsType.SuiteName);

Privacy manifest

NSUserDefaults is one of Apple's required reason APIs, so an app that uses LocalSettings or RoamingSettings on iOS or tvOS must declare it in its privacy manifest. Otherwise, App Store Connect rejects the upload. Make sure Platforms/iOS/PrivacyInfo.xcprivacy declares it inside the NSPrivacyAccessedAPITypes array of the manifest's root dictionary:

<dict>
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
        <string>CA92.1</string>
    </array>
</dict>

The CA92.1 reason covers reading and writing data that only the app itself can access, which matches the UnoApplicationData suite.

Note

Before Uno Platform 7.0, settings were stored directly in NSUserDefaults.StandardUserDefaults. Values written by those versions stay there, and remain invisible to ApplicationData, until the app explicitly migrates them. See the Uno Platform 7.0 migration guide for details.