Shaunebu.MAUI.PreferenceManager 1.0.0

Shaunebu.MAUI.PreferenceManager 📱🔧

Overview ✨

Shaunebu.MAUI.PreferenceManager is a powerful, type-safe wrapper around MAUI's built-in Preferences system that provides enhanced functionality, security, and superior developer experience for managing application settings in .NET MAUI applications.

Feature Comparison 🆚

Installation 📦

dotnet add package Shaunebu.MAUI.PreferenceManager

Quick Start 🚀

1. Setup Registration

// In MauiProgram.cs
builder.Services.AddPreferenceManager(options =>
{
    options.SharedName = "MyApp";
    options.EnableEncryption = true;
    options.EnableCaching = true;
    options.CacheDuration = TimeSpan.FromMinutes(10);
});

2. Basic Usage

public class MainViewModel
{
    private readonly IPreferenceManager _preferences;

    public MainViewModel(IPreferenceManager preferences)
    {
        _preferences = preferences;
    }

    // Store preferences
    _preferences.Set("Username", "JohnDoe");
    _preferences.Set("UserAge", 25);
    _preferences.Set("IsPremium", true);

    // Retrieve preferences
    var username = _preferences.Get<string>("Username");
    var age = _preferences.Get<int>("UserAge");
    var isPremium = _preferences.Get<bool>("IsPremium");
}

Core Features 🎯

1. Type-Safe Preferences 🏷️

// No more type-specific methods!
_preferences.Set("Temperature", 23.5);          // double
_preferences.Set("LastLogin", DateTime.Now);    // DateTime
_preferences.Set("UserSettings", userObject);   // Complex object

2. Complex Object Storage 🏢

public class UserSettings
{
    public string Theme { get; set; }
    public bool Notifications { get; set; }
    public int RefreshRate { get; set; }
}

var settings = new UserSettings { 
    Theme = "Dark", 
    Notifications = true 
};

// Automatic JSON serialization/deserialization
_preferences.Set("AppSettings", settings);
var loaded = _preferences.Get<UserSettings>("AppSettings");

3. Reactive Programming Support 🔄

// Subscribe to preference changes
_preferences.PreferenceChanged.Subscribe(args =>
{
    if (args.Key == "Theme")
    {
        // Update UI in real-time!
        ApplyTheme(args.NewValue?.ToString());
    }
});

// Trigger changes anywhere
_preferences.Set("Theme", "Dark"); // All subscribers notified!

4. Secure Storage 🔐

// Encrypt sensitive data
_preferences.SetSecure("AuthToken", "super-secret-token");
_preferences.SetSecure("UserCredentials", loginData);

// Decrypt automatically
var token = _preferences.GetSecure<string>("AuthToken");

5. Strongly-Typed Settings Manager 🎯

public class AppConfig
{
    public string Language { get; set; } = "en";
    public bool DarkMode { get; set; } = false;
    public int CacheSize { get; set; } = 100;
}

// Create typed manager
var configManager = new TypedPreferenceManager<AppConfig>(_preferences);

// Load all settings
var config = configManager.Load();

// Modify and save
config.DarkMode = true;
configManager.Save(config);

6. Migration Support 🚚

// Migrate from old key to new key
_preferences.MigratePreference("old_theme_key", "new_theme_key");

// Remove old key automatically
_preferences.MigratePreference("deprecated_setting", "new_setting", removeOld: true);

Advanced Usage 🛠️

Caching Configuration ⚡

builder.Services.AddPreferenceManager(options =>
{
    options.EnableCaching = true;
    options.CacheDuration = TimeSpan.FromMinutes(5); // Cache for 5 minutes
});

Error Handling 🚨

try
{
    var data = _preferences.Get<ComplexObject>("MyData");
}
catch (SerializationException ex)
{
    // Handle serialization errors
    Console.WriteLine($"Failed to deserialize: {ex.Message}");
}
catch (PreferenceManagerException ex)
{
    // Handle other preference errors
    Console.WriteLine($"Preference error: {ex.Message}");
}

Bulk Operations 📚

// Multiple preferences at once
var preferences = new Dictionary<string, object>
{
    ["Theme"] = "Dark",
    ["Notifications"] = true,
    ["FontSize"] = 14
};

foreach (var pref in preferences)
{
    _preferences.Set(pref.Key, pref.Value);
}

Performance Tips 🚀

1. Enable Caching: Reduces disk I/O for frequently accessed preferences

2. Use Appropriate Cache Duration: Balance between memory and freshness

3. Batch Related Settings: Use TypedPreferenceManager<T> for groups of settings

4. Disable Cache for Rarely Accessed Data: Set EnableCaching = false for large, rarely used objects

Best Practices 📝

✅ DO:

// Use descriptive keys
_preferences.Set("UserProfile_Theme", "Dark");

// Group related settings
_preferences.Set("Appearance_Theme", "Dark");
_preferences.Set("Appearance_FontSize", 14);

// Use secure storage for sensitive data
_preferences.SetSecure("Auth_Token", jwtToken);

❌ DON'T:

// Avoid generic keys
_preferences.Set("key1", data); // ❌ What is key1?

// Don't store large objects in preferences
_preferences.Set("LargeImage", hugeByteArray); // ❌ Use file storage instead

API Reference 📚

IPreferenceManager

TypedPreferenceManager<T>

Examples 🎨

Theme Management Example

public class ThemeService
{
    private readonly IPreferenceManager _preferences;

    public ThemeService(IPreferenceManager preferences)
    {
        _preferences = preferences;
        
        // React to theme changes
        _preferences.PreferenceChanged
            .Where(args => args.Key == "CurrentTheme")
            .Subscribe(args => ApplyTheme(args.NewValue?.ToString()));
    }

    public string CurrentTheme
    {
        get => _preferences.Get("CurrentTheme", "Light");
        set => _preferences.Set("CurrentTheme", value);
    }
}

User Settings Management

public class UserSettingsService
{
    private readonly TypedPreferenceManager<UserPreferences> _preferences;

    public UserSettingsService(IPreferenceManager preferenceManager)
    {
        _preferences = new TypedPreferenceManager<UserPreferences>(preferenceManager);
    }

    public UserPreferences GetSettings() => _preferences.Load();
    
    public void SaveSettings(UserPreferences settings) => _preferences.Save(settings);
    
    public void UpdateTheme(string theme)
    {
        var settings = _preferences.Load();
        settings.Theme = theme;
        _preferences.Save(settings);
    }
}