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
Preferences are stored with a String key. The value of a preference must be one of the following data types:
DateTime are stored in a 64-bit binary (long integer) format using two methods defined by the
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.
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);
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);
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
Remove method to remove a specific key from preferences:
To remove all keys, use the
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
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 and samples to integrate with the platform:
- Apple: Implementing an iOS Settings Bundle
- iOS Application Preferences Sample
- Android: Getting Started with Settings Screens
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.
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.
Performance may be impacted if you store large amounts of text, as the API was designed to store small amounts of text.