Xamarin Forms Data Persistence Preferences Securestorage Complete Guide

Table of Contents

1. Introduction to Xamarin.Forms Data Persistence
2. Using Preferences for Simple Data Storage
   • Step-by-Step Guide
   • Example Application
3. Using SecureStorage for Sensitive Data Storage
   • Step-by-Step Guide
   • Example Application
4. Handling Edge Cases and Best Practices
5. Conclusion

1. Introduction to Xamarin.Forms Data Persistence

Data persistence is crucial in any mobile application as it allows you to store user preferences, settings, or even small amounts of data locally. Xamarin.Forms provides two common ways to achieve data persistence:

• Preferences: Ideal for storing simple key-value pairs (e.g., user settings, preferences).
• SecureStorage: Used for securely storing sensitive information that should not be easily accessible (e.g., authentication tokens, passwords).

2. Using Preferences for Simple Data Storage

Step-by-Step Guide

Step 1: Install the Xamarin.Essentials NuGet Package

1. Open your Visual Studio solution.
2. Right-click on your .NET Standard Library project (the one containing your shared code) and select Manage NuGet Packages.
3. Search for Xamarin.Essentials and install the latest stable version.
4. Repeat the installation in any other projects that require access to Xamarin.Essentials (e.g., Android, iOS).

Step 2: Save Data Using Preferences

To save data, you can use the Preferences class. Here’s an example of saving a user’s theme preference:

using Xamarin.Essentials;

// Save a string value
Preferences.Set("theme", "dark");

// Save an integer value
Preferences.Set("fontSize", 14);

Step 3: Retrieve Data Using Preferences

To retrieve data, you can also use the Preferences class:

using Xamarin.Essentials;

// Retrieve a string value with a default value
string theme = Preferences.Get("theme", "light"); // Returns "dark" if saved, otherwise "light"

// Retrieve an integer value with a default value
int fontSize = Preferences.Get("fontSize", 12); // Returns 14 if saved, otherwise 12

Step 4: Remove Data from Preferences

If you need to remove a specific preference, use the Remove method:

using Xamarin.Essentials;

Preferences.Remove("theme");

To remove all preferences at once, use the Clear method:

using Xamarin.Essentials;

Preferences.Clear();

Example Application: Theme Switcher

Let’s create a simple Xamarin.Forms application that allows the user to switch between light and dark themes and persists this preference using Preferences.

Step 1: Create the Xamarin.Forms Project

1. Open Visual Studio.
2. Create a new Mobile App (.NET MAUI, .NET 6 - Visual) project. Alternatively, you can create a Xamarin.Forms App (iOS, Android, .NET Standard) project if you prefer.
3. Name your project and choose a location.

Step 2: Design the User Interface

Open MainPage.xaml and add the following XAML code to create a basic UI with a toggle switch for theme selection:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamarinFormsDataPersistence.MainPage"
             Title="Theme Switcher">
    <StackLayout Padding="30">
        <Label Text="Select Theme" FontSize="Large" HorizontalOptions="Center"
               FontAttributes="Bold" Margin="0,0,0,20"/>
        <HorizontalStackLayout HorizontalOptions="Center">
            <Label Text="Light" FontSize="Medium" />
            <Switch x:Name="themeSwitch" IsToggled="{Binding IsDarkTheme}" 
                    Toggled="OnThemeSwitchToggled" Margin="10,0" />
            <Label Text="Dark" FontSize="Medium" />
        </HorizontalStackLayout>
        <Label x:Name="statusLabel" FontSize="Medium" HorizontalOptions="Center"
               Margin="0,20,0,0" />
    </StackLayout>
</ContentPage>

If using Xamarin.Forms:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamarinFormsDataPersistence.MainPage"
             Title="Theme Switcher">
    <StackLayout Padding="30">
        <Label Text="Select Theme" FontSize="Large" HorizontalTextAlignment="Center"
               FontAttributes="Bold" Margin="0,0,0,20"/>
        <StackLayout Orientation="Horizontal" HorizontalOptions="Center">
            <Label Text="Light" FontSize="Medium" />
            <Switch x:Name="themeSwitch" IsToggled="{Binding IsDarkTheme}" 
                    Toggled="OnThemeSwitchToggled" Margin="10,0" />
            <Label Text="Dark" FontSize="Medium" />
        </StackLayout>
        <Label x:Name="statusLabel" FontSize="Medium" HorizontalTextAlignment="Center"
               Margin="0,20,0,0" />
    </StackLayout>
</ContentPage>

Step 3: Implement the ViewModel

Create a new class named MainPageViewModel.cs to handle the data binding and theme switching logic:

using Xamarin.Essentials;
using System.ComponentModel;
using System.Runtime.CompilerServices;

namespace XamarinFormsDataPersistence
{
    public class MainPageViewModel : INotifyPropertyChanged
    {
        private bool isDarkTheme;

        public bool IsDarkTheme
        {
            get => isDarkTheme;
            set
            {
                if (isDarkTheme != value)
                {
                    isDarkTheme = value;
                    OnPropertyChanged();
                    SaveThemePreference(isDarkTheme);
                }
            }
        }

        public MainPageViewModel()
        {
            // Load the saved theme preference
            IsDarkTheme = Preferences.Get("theme", false); // false = Light, true = Dark
        }

        private void SaveThemePreference(bool isDarkTheme)
        {
            Preferences.Set("theme", isDarkTheme);
        }

        public event PropertyChangedEventHandler PropertyChanged;

        protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = null)
        {
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
        }
    }
}

Step 4: Update the Code-Behind

Open MainPage.xaml.cs and set the BindingContext to the MainPageViewModel:

using Xamarin.Forms;
using Xamarin.Forms.Xaml;

namespace XamarinFormsDataPersistence
{
    [XamlCompilation(XamlCompilationOptions.Compile)]
    public partial class MainPage : ContentPage
    {
        private MainPageViewModel viewModel;

        public MainPage()
        {
            InitializeComponent();
            viewModel = new MainPageViewModel();
            BindingContext = viewModel;

            // Update the UI based on the saved theme
            UpdateTheme();
        }

        private void OnThemeSwitchToggled(object sender, ToggledEventArgs e)
        {
            // Update the UI based on the new theme
            UpdateTheme();
            statusLabel.Text = $"Theme is now {(viewModel.IsDarkTheme ? "Dark" : "Light")}.";
        }

        private void UpdateTheme()
        {
            if (viewModel.IsDarkTheme)
            {
                // Set dark theme colors
                this.Resources["BackgroundColor"] = Color.FromHex("#121212");
                this.Resources["TextColor"] = Color.FromHex("#FFFFFF");
            }
            else
            {
                // Set light theme colors
                this.Resources["BackgroundColor"] = Color.FromHex("#FFFFFF");
                this.Resources["TextColor"] = Color.FromHex("#000000");
            }
        }
    }
}

Step 5: Add Resources for Theme Colors

To make the theme switching more dynamic, you can define colors in the App.xaml file:

Open App.xaml and add the following:

<?xml version="1.0" encoding="utf-8" ?>
<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamarinFormsDataPersistence.App">
    <Application.Resources>
        <ResourceDictionary>
            <Color x:Key="BackgroundColor">#FFFFFF</Color>
            <Color x:Key="TextColor">#000000</Color>
        </ResourceDictionary>
    </Application.Resources>
</Application>

If using Xamarin.Forms, modify App.xaml as follows:

<?xml version="1.0" encoding="utf-8" ?>
<Application xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamarinFormsDataPersistence.App">
    <Application.Resources>
        <ResourceDictionary>
            <Color x:Key="BackgroundColor">#FFFFFF</Color>
            <Color x:Key="TextColor">#000000</Color>
        </ResourceDictionary>
    </Application.Resources>
</Application>

Step 6: Update the MainPage.xaml to Use Resources

Ensure that your MainPage.xaml uses these resources:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamarinFormsDataPersistence.MainPage"
             Title="Theme Switcher">
    <ContentPage.Resources>
        <ResourceDictionary>
            <Style TargetType="Label">
                <Setter Property="TextColor" Value="{DynamicResource TextColor}" />
            </Style>
            <Style TargetType="Switch">
                <Setter Property="OnColor" Value="{DynamicResource TextColor}" />
            </Style>
        </ResourceDictionary>
    </ContentPage.Resources>
    <StackLayout Padding="30" BackgroundColor="{DynamicResource BackgroundColor}">
        <Label Text="Select Theme" FontSize="Large" HorizontalTextAlignment="Center"
               FontAttributes="Bold" Margin="0,0,0,20"/>
        <StackLayout Orientation="Horizontal" HorizontalOptions="Center">
            <Label Text="Light" FontSize="Medium" />
            <Switch x:Name="themeSwitch" IsToggled="{Binding IsDarkTheme}" 
                    Toggled="OnThemeSwitchToggled" Margin="10,0" />
            <Label Text="Dark" FontSize="Medium" />
        </StackLayout>
        <Label x:Name="statusLabel" FontSize="Medium" HorizontalTextAlignment="Center"
               Margin="0,20,0,0" />
    </StackLayout>
</ContentPage>

If using Xamarin.Forms:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamarinFormsDataPersistence.MainPage"
             Title="Theme Switcher">
    <ContentPage.Resources>
        <ResourceDictionary>
            <Style TargetType="Label">
                <Setter Property="TextColor" Value="{DynamicResource TextColor}" />
            </Style>
            <Style TargetType="Switch">
                <Setter Property="OnColor" Value="{DynamicResource TextColor}" />
            </Style>
        </ResourceDictionary>
    </ContentPage.Resources>
    <StackLayout Padding="30" BackgroundColor="{DynamicResource BackgroundColor}">
        <Label Text="Select Theme" FontSize="Large" HorizontalTextAlignment="Center"
               FontAttributes="Bold" Margin="0,0,0,20"/>
        <StackLayout Orientation="Horizontal" HorizontalOptions="Center">
            <Label Text="Light" FontSize="Medium" />
            <Switch x:Name="themeSwitch" IsToggled="{Binding IsDarkTheme}" 
                    Toggled="OnThemeSwitchToggled" Margin="10,0" />
            <Label Text="Dark" FontSize="Medium" />
        </StackLayout>
        <Label x:Name="statusLabel" FontSize="Medium" HorizontalTextAlignment="Center"
               Margin="0,20,0,0" />
    </StackLayout>
</ContentPage>

Demonstration

• Build and Run your application on an emulator or a physical device.
• Toggle the switch to switch between light and dark themes.
• Restart the application to see that the selected theme persists.

3. Using SecureStorage for Sensitive Data Storage

Step-by-Step Guide

Step 1: Install the Xamarin.Essentials NuGet Package

As mentioned earlier, ensure that you have the Xamarin.Essentials package installed in your projects.

Step 2: Save Data Using SecureStorage

SecureStorage is designed to store small amounts of sensitive information securely:

using Xamarin.Essentials;

// Save a string value
await SecureStorage.SetAsync("api_token", "your_api_token_here");

Step 3: Retrieve Data Using SecureStorage

To retrieve a value, use the GetAsync method:

using Xamarin.Essentials;

// Retrieve a string value
string apiToken = await SecureStorage.GetAsync("api_token");

Step 4: Remove Data from SecureStorage

If you need to remove a specific item or all items, use the following methods:

using Xamarin.Essentials;

// Remove a specific item
await SecureStorage.RemoveAsync("api_token");

// Remove all items
await SecureStorage.RemoveAllAsync();

Example Application: Secure Password Storage

Let’s create a simple application where the user can enter and save a password securely using SecureStorage.

Step 1: Create the Xamarin.Forms Project

You can use the same project created in the previous example or create a new one.

Step 2: Design the User Interface

Open MainPage.xaml and add the following XAML code to create a UI for entering and saving a password:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamarinFormsDataPersistence.MainPage"
             Title="Password Manager">
    <StackLayout Padding="30">
        <Label Text="Enter and Save Password" FontSize="Large" HorizontalTextAlignment="Center"
               FontAttributes="Bold" Margin="0,0,0,20"/>
        <Entry x:Name="passwordEntry" Placeholder="Enter password" FontSize="Medium"
               IsPassword="True" Margin="0,0,0,10"/>
        <Button Text="Save Password" Clicked="OnSavePasswordClicked" FontSize="Medium"
                HorizontalOptions="FillAndExpand" Margin="0,0,0,20"/>
        <Button Text="Retrieve Password" Clicked="OnRetrievePasswordClicked" FontSize="Medium"
                HorizontalOptions="FillAndExpand" Margin="0,0,0,20"/>
        <Label x:Name="statusLabel" FontSize="Medium" HorizontalTextAlignment="Center"
               Margin="0,20,0,0" />
    </StackLayout>
</ContentPage>

If using Xamarin.Forms:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamarinFormsDataPersistence.MainPage"
             Title="Password Manager">
    <StackLayout Padding="30">
        <Label Text="Enter and Save Password" FontSize="Large" HorizontalTextAlignment="Center"
               FontAttributes="Bold" Margin="0,0,0,20"/>
        <Entry x:Name="passwordEntry" Placeholder="Enter password" FontSize="Medium"
               IsPassword="True" Margin="0,0,0,10"/>
        <Button Text="Save Password" Clicked="OnSavePasswordClicked" FontSize="Medium"
                HorizontalOptions="FillAndExpand" Margin="0,0,0,20"/>
        <Button Text="Retrieve Password" Clicked="OnRetrievePasswordClicked" FontSize="Medium"
                HorizontalOptions="FillAndExpand" Margin="0,0,0,20"/>
        <Label x:Name="statusLabel" FontSize="Medium" HorizontalTextAlignment="Center"
               Margin="0,20,0,0" />
    </StackLayout>
</ContentPage>

Step 3: Implement the Logic in Code-Behind

Open MainPage.xaml.cs and implement the methods to save and retrieve the password:

using Xamarin.Essentials;
using Xamarin.Forms;
using Xamarin.Forms.Xaml;

namespace XamarinFormsDataPersistence
{
    [XamlCompilation(XamlCompilationOptions.Compile)]
    public partial class MainPage : ContentPage
    {
        private const string PasswordKey = "password";

        public MainPage()
        {
            InitializeComponent();
        }

        private async void OnSavePasswordClicked(object sender, System.EventArgs e)
        {
            string password = passwordEntry.Text;
            if (string.IsNullOrWhiteSpace(password))
            {
                statusLabel.Text = "Please enter a password.";
                return;
            }

            try
            {
                await SecureStorage.SetAsync(PasswordKey, password);
                statusLabel.Text = "Password saved successfully.";
                passwordEntry.Text = string.Empty; // Clear the entry
            }
            catch (Exception ex)
            {
                statusLabel.Text = $"Error saving password: {ex.Message}";
            }
        }

        private async void OnRetrievePasswordClicked(object sender, System.EventArgs e)
        {
            try
            {
                string password = await SecureStorage.GetAsync(PasswordKey);
                if (password != null)
                {
                    statusLabel.Text = $"Retrieved password: {password}";
                }
                else
                {
                    statusLabel.Text = "No password found.";
                }
            }
            catch (Exception ex)
            {
                statusLabel.Text = $"Error retrieving password: {ex.Message}";
            }
        }
    }
}

Demonstration

• Build and Run your application on an emulator or a physical device.
• Enter a password and click Save Password.
• Click Retrieve Password to see the saved password.
• Restart the application to verify that the password persists.

4. Handling Edge Cases and Best Practices

Handling NotImplementedException

Sometimes, SecureStorage might not be supported on certain platforms or configurations. Always handle exceptions to avoid crashes:

try
{
    await SecureStorage.SetAsync("key", "value");
}
catch (NotImplementedException ex)
{
    statusLabel.Text = "SecureStorage not implemented on this platform.";
}
catch (Exception ex)
{
    statusLabel.Text = $"Error: {ex.Message}";
}

Validating Input

Before saving data, validate the input to ensure it meets your criteria (e.g., password strength, non-null values):

private async void OnSavePasswordClicked(object sender, System.EventArgs e)
{
    string password = passwordEntry.Text;
    if (string.IsNullOrWhiteSpace(password) || password.Length < 6)
    {
        statusLabel.Text = "Please enter a valid password (at least 6 characters).";
        return;
    }

    try
    {
        await SecureStorage.SetAsync(PasswordKey, password);
        statusLabel.Text = "Password saved successfully.";
        passwordEntry.Text = string.Empty; // Clear the entry
    }
    catch (Exception ex)
    {
        statusLabel.Text = $"Error saving password: {ex.Message}";
    }
}

Clearing Cached Data

When a user logs out or logs in from a different account, clear any cached sensitive data:

private async void OnLogoutClicked(object sender, System.EventArgs e)
{
    // Clear SecureStorage
    await SecureStorage.RemoveAsync("api_token");
    await SecureStorage.RemoveAsync("user_id");

    // Clear Preferences
    Preferences.Clear();

    // Redirect to login page or reset UI
    await Navigation.PopToRootAsync();
}

Security Considerations

• Avoid saving sensitive information in Preferences as they are not encrypted.
• Use SecureStorage for sensitive data only.
• Regularly update the Xamarin.Essentials package to the latest version to benefit from security patches and improvements.

Memory Management

Ensure that you manage memory appropriately, especially when dealing with sensitive data. For instance, avoid keeping sensitive information in variables or properties longer than necessary.

Error Handling

Implement robust error handling to manage exceptions gracefully and provide meaningful feedback to the user.

5. Conclusion

Congratulations on learning how to use Preferences and SecureStorage for data persistence in Xamarin.Forms applications! You should now be able to create applications that store user preferences and sensitive information securely.

Summary

• Preferences: Used for storing simple key-value pairs, ideal for app settings.
• SecureStorage: Used for storing sensitive data securely, ensuring that this information is protected.

Further Reading

• Xamarin.Essentials Preferences Documentation
• Xamarin.Essentials SecureStorage Documentation
• Xamarin.Forms Data Storage Documentation

Feel free to experiment with Preferences and SecureStorage and explore other features offered by Xamarin.Forms and Xamarin.Essentials to build robust and secure mobile applications. Happy coding!