Training
Module
Store local data with SQLite in a .NET MAUI app - Training
Learn how to store and access data held in SQLite using a .NET Multi-platform App UI (MAUI) app
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) ISecureStorage
interface. This interface helps securely store simple key/value pairs.
The default implementation of the ISecureStorage
interface is available through the SecureStorage.Default
property. Both the ISecureStorage
interface and SecureStorage
class are contained in the Microsoft.Maui.Storage
namespace.
To access the SecureStorage functionality, the following platform-specific setup is required:
Auto Backup for Apps is a feature of Android 6.0 (API level 23) and later that backs up user's app data (shared preferences, files in the app's internal storage, and other specific files). Data is restored when an app is reinstalled or installed on a new device. This can affect SecureStorage
, which utilizes share preferences that are backed up and can't be decrypted when the restore occurs. .NET MAUI automatically handles this case by removing the key so it can be reset. Alternatively, you can disable Auto Backup.
You can choose to disable Auto Backup for your entire application by setting android:allowBackup
to false in the AndroidManifest.xml file. This approach is only recommended if you plan on restoring data in another way.
<manifest ... >
...
<application android:allowBackup="false" ... >
...
</application>
</manifest>
Auto Backup can be configured to disable specific content from backing up. You can create a custom rule set to exclude SecureStore
items from being backed up.
Set the android:fullBackupContent
attribute in your AndroidManifest.xml:
<application ...
android:fullBackupContent="@xml/auto_backup_rules">
</application>
Create a new XML file named auto_backup_rules.xml in the Platforms/Android/Resources/xml directory with the build action of AndroidResource. Set the following content that includes all shared preferences except for SecureStorage
:
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
<include domain="sharedpref" path="."/>
<exclude domain="sharedpref" path="${applicationId}.microsoft.maui.essentials.preferences.xml"/>
</full-backup-content>
The following code examples demonstrate how to use secure storage.
Tip
It's possible that an exception is thrown when calling GetAsync
or SetAsync
. This can be caused by a device not supporting secure storage, encryption keys changing, or corruption of data. it's best to handle this by removing and adding the setting back if possible.
To save a value for a given key in secure storage:
await SecureStorage.Default.SetAsync("oauth_token", "secret-oauth-token-value");
To retrieve a value from secure storage:
string oauthToken = await SecureStorage.Default.GetAsync("oauth_token");
if (oauthToken == null)
{
// No value is associated with the key "oauth_token"
}
Tip
If there isn't a value associated with the key, GetAsync
returns null
.
To remove a specific value, remove the key:
bool success = SecureStorage.Default.Remove("oauth_token");
To remove all values, use the RemoveAll
method:
SecureStorage.Default.RemoveAll();
This section describes the platform-specific differences with the secure storage API.
SecureStorage
uses the Preferences API and follows the same data persistence outlined in the Preferences documentation, with a filename of [YOUR-APP-PACKAGE-ID].microsoft.maui.essentials.preferences. However, data is encrypted with the Android EncryptedSharedPreferences
class, from the Android Security library, which wraps the SharedPreferences
class and automatically encrypts keys and values using a two-scheme approach:
For more information about the Android Security library, see Work with data more securely on developer.android.com.
Performance may be impacted if you store large amounts of text, as the API was designed to store small amounts of text.
.NET MAUI feedback
.NET MAUI is an open source project. Select a link to provide feedback:
Training
Module
Store local data with SQLite in a .NET MAUI app - Training
Learn how to store and access data held in SQLite using a .NET Multi-platform App UI (MAUI) app