Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/JasonWei512/WinUI-ObservableSettings
⚙ A C# source generator to generate observable, strong-typed properties for reading and writing settings in WinUI 3 app.
https://github.com/JasonWei512/WinUI-ObservableSettings
dotnet source-generator sourcegenerator winui winui3
Last synced: 28 days ago
JSON representation
⚙ A C# source generator to generate observable, strong-typed properties for reading and writing settings in WinUI 3 app.
- Host: GitHub
- URL: https://github.com/JasonWei512/WinUI-ObservableSettings
- Owner: JasonWei512
- License: mit
- Created: 2023-08-28T11:41:42.000Z (over 1 year ago)
- Default Branch: develop
- Last Pushed: 2023-09-11T13:06:28.000Z (over 1 year ago)
- Last Synced: 2024-05-12T13:31:00.452Z (7 months ago)
- Topics: dotnet, source-generator, sourcegenerator, winui, winui3
- Language: C#
- Homepage: https://www.nuget.org/packages/NickJohn.WinUI.ObservableSettings
- Size: 58.6 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- csharp-source-generators - WinUI-ObservableSettings -   - Generate boilerplates to read and write settings in packaged WinUI 3 app. (Source Generators / XAML / WPF / Avalonia)
README
# WinUI ObservableSettings
[](https://www.nuget.org/packages/NickJohn.WinUI.ObservableSettings)
[](https://github.com/JasonWei512/WinUI-ObservableSettings/actions/workflows/ci.yml)
A C# source generator to help you generate boilerplates to read and write settings in [Windows.Storage.ApplicationData.Current.LocalSettings](https://learn.microsoft.com/en-us/windows/apps/design/app-settings/store-and-retrieve-app-data#retrieve-the-local-app-data-store) 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](https://www.nuget.org/packages/NickJohn.WinUI.ObservableSettings).
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:
```csharp
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:
```csharp
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>? 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:
```csharp
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:
```csharp
public partial class SettingsService : INotifyPropertyChanged
{
private IPropertySet LocalSettings => Windows.Storage.ApplicationData.Current.LocalSettings.Values;
public event PropertyChangedEventHandler? PropertyChanged;
public event EventHandler>? 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.Default.Equals(oldValue, value))
{
LocalSettings["Volume"] = value;
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs("Volume"));
VolumeChanged?.Invoke(this, new SettingValueChangedEventArgs(oldValue, value));
}
}
}
}
```
## Provide an explicit setting key
- It's highly recommended to provide an explicit `settingKey` to the `[ObservableSetting]` attribute.
```csharp
[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).
```csharp
[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](https://learn.microsoft.com/en-us/windows/apps/design/app-settings/store-and-retrieve-app-data#settings) 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](https://learn.microsoft.com/en-us/uwp/api/windows.storage.applicationdata.localsettings#remarks):
- 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:
- https://github.com/joseangelmt/ObservableSettings
- [Microsoft MVVM Toolkit Source Generators](https://github.com/CommunityToolkit/dotnet)