Wino-Mail/Wino.Core.WinUI/MIGRATION_NewThemeService.md

NewThemeService Migration Guide

Overview

This guide helps you migrate from the original ThemeService to the new NewThemeService with enhanced backdrop management and improved accent color handling.

Quick Migration Steps

1. Update Service Usage

Before (Old ThemeService):

var themeService = Services.GetService<IThemeService>();
themeService.RootTheme = ApplicationElementTheme.Dark;
themeService.AccentColor = "#FF5722";

After (NewThemeService):

var newThemeService = Services.GetService<INewThemeService>();
newThemeService.RootTheme = ApplicationElementTheme.Dark;
await newThemeService.SetAccentColorAsync("#FF5722", preserveTheme: true);

// Plus new backdrop management
await newThemeService.ApplyBackdropAsync(WindowBackdropType.Mica);

2. Remove Hardcoded Backdrops

Before:

<winuiex:WindowEx.SystemBackdrop>
    <MicaBackdrop />
</winuiex:WindowEx.SystemBackdrop>

After:

<!--  SystemBackdrop will be set by NewThemeService  -->

3. Update App Initialization

Before:

protected override async void OnLaunched(LaunchActivatedEventArgs args)
{
    MainWindow = new ShellWindow();
    await InitializeServicesAsync();
    MainWindow.Activate();
}

After:

protected override async void OnLaunched(LaunchActivatedEventArgs args)
{
    // Load backdrop settings before creating window
    var newThemeService = Services.GetService<INewThemeService>();
    var configService = Services.GetService<IConfigurationService>();
    var savedBackdropType = (WindowBackdropType)configService.Get("WindowBackdropTypeKey", (int)WindowBackdropType.Mica);

    MainWindow = new ShellWindow();
    
    // Apply backdrop immediately after window creation
    if (newThemeService != null)
    {
        await newThemeService.ApplyBackdropAsync(savedBackdropType);
    }
    
    await InitializeServicesAsync();
    MainWindow.Activate();
}

4. Update WinoApplication Services

Before:

public IEnumerable<IInitializeAsync> GetActivationServices()
{
    yield return DatabaseService;
    yield return TranslationService;
    yield return ThemeService;  // Old service
}

After:

public IEnumerable<IInitializeAsync> GetActivationServices()
{
    yield return DatabaseService;
    yield return TranslationService;
    yield return NewThemeService;  // New service
    // yield return ThemeService;  // Keep for backward compatibility but don't initialize
}

New Features Available After Migration

1. Backdrop Management

// All available backdrop types
await newThemeService.ApplyBackdropAsync(WindowBackdropType.Mica);
await newThemeService.ApplyBackdropAsync(WindowBackdropType.MicaAlt);
await newThemeService.ApplyBackdropAsync(WindowBackdropType.DesktopAcrylic);
await newThemeService.ApplyBackdropAsync(WindowBackdropType.AcrylicBase);
await newThemeService.ApplyBackdropAsync(WindowBackdropType.AcrylicThin);
await newThemeService.ApplyBackdropAsync(WindowBackdropType.None);

// Persistent backdrop setting
newThemeService.CurrentBackdropType = WindowBackdropType.MicaAlt;

2. Enhanced Accent Color Management

// Set accent color without changing theme
await newThemeService.SetAccentColorAsync("#FF5722", preserveTheme: true);

// Get system accent color
var systemColor = newThemeService.GetSystemAccentColorHex();
await newThemeService.SetAccentColorAsync(systemColor);

3. Event Handling

// New backdrop change events
newThemeService.BackdropChanged += (sender, backdropType) => {
    // Handle backdrop changes
    UpdateUI(backdropType);
};

// Existing events still work
newThemeService.ElementThemeChanged += (sender, theme) => {
    // Handle theme changes
};

newThemeService.AccentColorChanged += (sender, color) => {
    // Handle accent color changes
};

Backward Compatibility

Both Services Available

• IThemeService (original) - still registered and functional
• INewThemeService (new) - enhanced version with additional features

Choosing Which to Use

// For new code - use NewThemeService
var newThemeService = Services.GetService<INewThemeService>();

// For existing code that needs compatibility - keep using ThemeService
var oldThemeService = Services.GetService<IThemeService>();

Gradual Migration Strategy

1. Phase 1: Register both services, initialize NewThemeService
2. Phase 2: Update new features to use NewThemeService
3. Phase 3: Migrate existing code gradually
4. Phase 4: Eventually phase out old ThemeService (optional)

Common Migration Issues

Issue 1: Window Backdrop Not Applied

Problem: Backdrop doesn't appear after migration Solution: Ensure backdrop is applied after window creation but before activation

MainWindow = new ShellWindow();
await newThemeService.ApplyBackdropAsync(WindowBackdropType.Mica); // Add this
await InitializeServicesAsync();
MainWindow.Activate();

Issue 2: Accent Color Changes Don't Persist

Problem: Accent color resets after app restart Solution: Use the enhanced SetAccentColorAsync method

// Old way - might not persist properly
newThemeService.AccentColor = "#FF5722";

// New way - properly persisted
await newThemeService.SetAccentColorAsync("#FF5722", preserveTheme: true);

Issue 3: Multiple Service Initialization

Problem: Both services being initialized causing conflicts Solution: Only initialize NewThemeService in GetActivationServices()

public IEnumerable<IInitializeAsync> GetActivationServices()
{
    yield return DatabaseService;
    yield return TranslationService;
    yield return NewThemeService;  // Only this one
    // Don't yield ThemeService here
}

Testing Your Migration

1. Backdrop Functionality

• App starts with saved backdrop type
• Backdrop changes are applied immediately
• Backdrop changes persist after app restart
• All backdrop types work correctly

2. Theme Functionality

• Light/Dark theme changes work
• Custom themes still function
• Theme changes persist after restart

3. Accent Color Management

• Custom accent colors apply correctly
• System accent color detection works
• Accent color changes persist
• Theme preservation works with accent changes

4. Backward Compatibility

• Existing custom themes still work
• Old theme-related code continues to function
• No regression in existing functionality

Performance Considerations

Initialization Order

• NewThemeService initializes backdrop settings from saved configuration
• Window creation happens before service initialization for best performance
• Backdrop is applied immediately after window creation

Runtime Performance

• Backdrop changes are async operations
• Don't change backdrop frequently (e.g., during animations)
• Cache backdrop type to avoid unnecessary changes

Complete Migration Checklist

• Update DI container registration
• Update WinoApplication service initialization
• Remove hardcoded SystemBackdrop from XAML
• Update app launch sequence
• Update settings/preferences UI for backdrop options
• Test all backdrop types
• Test theme and accent color functionality
• Verify persistence across app restarts
• Update documentation and comments
• Train team on new features

Need Help?

If you encounter issues during migration:

1. Check the complete example in NewThemeServiceExampleViewModel
2. Review the full documentation in README_NewThemeService.md
3. Ensure proper initialization order in your app
4. Verify all required using statements are included