Preferences

Article
08/27/2024

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IPreferences interface. This interface helps store app preferences in a key/value store.

The default implementation of the IPreferences interface is available through the Preferences.Default property. Both the IPreferences interface and Preferences class are contained in the Microsoft.Maui.Storage namespace.

Storage types

Preferences are stored with a String key. The value of a preference must be one of the following data types:

Values of DateTime are stored in a 64-bit binary (long integer) format using two methods defined by the DateTime class:

The ToBinary method is used to encode the DateTime value.
The FromBinary method decodes the value.

See the documentation of these methods for adjustments that might be made to decoded values when a DateTime is stored that isn't a Coordinated Universal Time (UTC) value.

Set preferences

Preferences are set by calling the Preferences.Set method, providing the key and value:

// Set a string value:
Preferences.Default.Set("first_name", "John");

// Set an numerical value:
Preferences.Default.Set("age", 28);

// Set a boolean value:
Preferences.Default.Set("has_pets", true);

Get preferences

To retrieve a value from preferences you pass the key of the preference, followed by the default value when the key doesn't exist:

string firstName = Preferences.Default.Get("first_name", "Unknown");
int age = Preferences.Default.Get("age", -1);
bool hasPets = Preferences.Default.Get("has_pets", false);

In some scenarios you may need to pass the key of the preference, followed by the default value and its type:

long value = Preferences.Get("master_date", (long)0);

Check for a key

It may be useful to check if a key exists in the preferences or not. Even though Get has you set a default value when the key doesn't exist, there may be cases where the key existed, but the value of the key matched the default value. So you can't rely on the default value as an indicator that the key doesn't exist. Use the ContainsKey method to determine if a key exists:

bool hasKey = Preferences.Default.ContainsKey("my_key");

Remove one or all keys

Use the Remove method to remove a specific key from preferences:

Preferences.Default.Remove("first_name");

To remove all keys, use the Clear method:

Preferences.Default.Clear();

Shared keys

The preferences stored by your app are only visible to your app. However, you can also create a shared preference that can be used by other extensions or a watch app. When you set, remove, or retrieve a preference, an optional string parameter can be supplied to specify the name of the container the preference is stored in.

The following methods take a string parameter named sharedName:

Preferences.Set
Preferences.Get
Preferences.Remove
Preferences.Clear

Important

Please read the platform implementation specifics, as shared preferences have behavior-specific implementations

Integrate with system settings

Preferences are stored natively, which allows you to integrate your settings into the native system settings. Follow the platform documentation to integrate with the platform:

Apple: Implementing an iOS Settings Bundle
Android: Getting Started with Settings Screens

Platform differences

This section describes the platform-specific differences with the preferences API.

All data is stored into Shared Preferences. If no sharedName is specified, the default Shared Preferences are used. Otherwise, the name is used to get a private Shared Preferences with the specified name.

Persistence

Uninstalling the application causes all preferences to be removed, except when the app runs on Android 6.0 (API level 23) or later, while using the Auto Backup feature. This feature is on by default and preserves app data, including Shared Preferences, which is what the Preferences API uses. You can disable this by following Google's Auto Backup documentation.

Limitations

Performance may be impacted if you store large amounts of text, as the API was designed to store small amounts of text.

Share via