NickJohn.WinUI.ObservableSettings 1.0.0

dotnet add package NickJohn.WinUI.ObservableSettings --version 1.0.0                
NuGet\Install-Package NickJohn.WinUI.ObservableSettings -Version 1.0.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="NickJohn.WinUI.ObservableSettings" Version="1.0.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add NickJohn.WinUI.ObservableSettings --version 1.0.0                
#r "nuget: NickJohn.WinUI.ObservableSettings, 1.0.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install NickJohn.WinUI.ObservableSettings as a Cake Addin
#addin nuget:?package=NickJohn.WinUI.ObservableSettings&version=1.0.0

// Install NickJohn.WinUI.ObservableSettings as a Cake Tool
#tool nuget:?package=NickJohn.WinUI.ObservableSettings&version=1.0.0                

WinUI ObservableSettings

Nuget build & test

A C# source generator to help you generate boilerplates to read and write settings in Windows.Storage.ApplicationData.Current.LocalSettings in packaged WinUI 3 app.

It will generate a partial class that:

  • Has strong-typed properties to read and write settings in storage
  • Implements INotifyPropertyChanged so you can bind to it in XAML
  • Raises an event when setting value changes

Quickstart

  1. Install NickJohn.WinUI.ObservableSettings from Nuget.

  2. Say you want to store a Volume as double in storage, with the default value 0.75.

    All you need to do is adding an [ObservableSetting] attribute to the default value field:

    using NickJohn.WinUI.ObservableSettings;
    ...
    public partial class SettingsService    // Don't forget to add "partial" keyword to the class!
    {
        [ObservableSetting("Volume")]   // The "Volume" here is the key of the setting in storage
        private readonly double volume = 0.75;  // This field is used as the default setting value
    }
    

    It will generate a partial class:

    public partial class SettingsService : INotifyPropertyChanged
    {
        // You can bind to "Volume" in XAML
        public event PropertyChangedEventHandler? PropertyChanged;
    
        // When the setting "Volume" changes, this event will be raised
        public event EventHandler<SettingValueChangedEventArgs<double>>? VolumeChanged;
    
        // Strong typed "Volume" property to read and write setting in storage
        public double Volume 
        {
            get { ... } // Read setting from storage
            set { ... } // Write setting to storage
        }
    }
    
  3. Now you can use the generated class to read and write settings:

    SettingsService settingsService = new SettingsService();
    
    // Handle setting value changed events
    settingsService.VolumeChanged += (s, e) => 
    {
        Debug.WriteLine($"Volume changed from {e.OldValue} to {e.NewValue}");
    }
    
    Volume volume = settingsService.Volume; // Read settings from storage
    
    volume = volume / 2;
    
    settingsService.Volume = volume // Write settings to storage
    

Details

How does the generated class look like?

Basically like this:

public partial class SettingsService : INotifyPropertyChanged
{
    private IPropertySet LocalSettings => Windows.Storage.ApplicationData.Current.LocalSettings.Values;

    public event PropertyChangedEventHandler? PropertyChanged;

    public event EventHandler<SettingValueChangedEventArgs<double>>? VolumeChanged;
        
    public double Volume
    {
        get
        {
            if (LocalSettings.TryGetValue("Volume", out object? settingObject))
            {
                if (settingObject is double settingValue)
                {
                    return settingValue;
                }
            }
            return volume;
        }
        set
        {
            double oldValue = Volume;
            if (!EqualityComparer<double>.Default.Equals(oldValue, value))
            {
                LocalSettings["Volume"] = value;
                PropertyChanged?.Invoke(this, new PropertyChangedEventArgs("Volume"));
                VolumeChanged?.Invoke(this, new SettingValueChangedEventArgs<double>(oldValue, value));
            }
        }
    }
}

Provide an explicit setting key

  • It's highly recommended to provide an explicit settingKey to the [ObservableSetting] attribute.

    [ObservableSetting("UserEmail")]
    private readonly string userEmail = "";
    
  • If you don't, the Pascal form of the attributed field name will be used (same as the generated property name).

    [ObservableSetting] // Setting key is "UserEmail"
    private readonly string userEmail = "";
    

    ⚠ But if you don't provide an explicit settingKey, when you renames the attributed field, the setting key will change, and the saved setting will not be read correctly!

How are the settings stored?

Some types can be directly stored in Windows.Storage.ApplicationData.Current.LocalSettings.

  • If the type of the setting to save is one of these "native" setting types, it will be directly stored in storage.

  • Otherwise, it will be serialized as JSON with System.Text.Json and saved as string.

Setting size limit

According to the official documents:

  • Each setting key can be 255 characters in length at most.
  • Each setting can be up to 8K bytes in size.

Acknowledgements

This project is inspired by:

Product Compatible and additional computed target framework versions.
.NET net5.0-windows10.0.17763 is compatible.  net6.0-windows was computed.  net6.0-windows10.0.17763 is compatible.  net7.0-windows was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net5.0-windows10.0.17763

    • No dependencies.
  • net6.0-windows10.0.17763

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on NickJohn.WinUI.ObservableSettings:

Repository Stars
JasonWei512/EnergyStarX
🔋 Improve your Windows 11 device's battery life. A WinUI 3 GUI for https://github.com/imbushuo/EnergyStar.
Version Downloads Last updated
1.0.0 959 9/5/2023
0.0.3 565 9/3/2023
0.0.2 568 8/31/2023
0.0.1 583 8/28/2023