{"id":15059821,"url":"https://github.com/jasonwei512/winui-observablesettings","last_synced_at":"2025-04-14T02:14:51.569Z","repository":{"id":191155721,"uuid":"684066984","full_name":"JasonWei512/WinUI-ObservableSettings","owner":"JasonWei512","description":"⚙ A C# source generator to generate observable, strong-typed properties for reading and writing settings in WinUI 3 app.","archived":false,"fork":false,"pushed_at":"2023-09-11T13:06:28.000Z","size":60,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-04-14T02:14:39.119Z","etag":null,"topics":["dotnet","source-generator","sourcegenerator","winui","winui3"],"latest_commit_sha":null,"homepage":"https://www.nuget.org/packages/NickJohn.WinUI.ObservableSettings","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JasonWei512.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-28T11:41:42.000Z","updated_at":"2025-03-06T12:20:31.000Z","dependencies_parsed_at":"2024-08-03T02:23:16.137Z","dependency_job_id":"5f9319da-58ff-4e4c-8940-c74ccb4adb68","html_url":"https://github.com/JasonWei512/WinUI-ObservableSettings","commit_stats":null,"previous_names":["jasonwei512/winui-observablesettings"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonWei512%2FWinUI-ObservableSettings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonWei512%2FWinUI-ObservableSettings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonWei512%2FWinUI-ObservableSettings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonWei512%2FWinUI-ObservableSettings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JasonWei512","download_url":"https://codeload.github.com/JasonWei512/WinUI-ObservableSettings/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809059,"owners_count":21164896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dotnet","source-generator","sourcegenerator","winui","winui3"],"created_at":"2024-09-24T22:48:20.320Z","updated_at":"2025-04-14T02:14:51.548Z","avatar_url":"https://github.com/JasonWei512.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WinUI ObservableSettings\n\n[![Nuget](https://img.shields.io/nuget/v/NickJohn.WinUI.ObservableSettings)](https://www.nuget.org/packages/NickJohn.WinUI.ObservableSettings)\n[![build \u0026 test](https://github.com/JasonWei512/WinUI-ObservableSettings/actions/workflows/ci.yml/badge.svg)](https://github.com/JasonWei512/WinUI-ObservableSettings/actions/workflows/ci.yml)\n\nA 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.\n\nIt will generate a partial class that:\n- Has strong-typed properties to read and write settings in storage\n- Implements `INotifyPropertyChanged` so you can bind to it in XAML\n- Raises an event when setting value changes\n\n\n# Quickstart\n\n1.  Install `NickJohn.WinUI.ObservableSettings` from [Nuget](https://www.nuget.org/packages/NickJohn.WinUI.ObservableSettings).\n\n2.  Say you want to store a `Volume` as `double` in storage, with the default value `0.75`.\n\n    All you need to do is adding an `[ObservableSetting]` attribute to the default value field:\n\n    ```csharp\n    using NickJohn.WinUI.ObservableSettings;\n    ...\n    public partial class SettingsService    // Don't forget to add \"partial\" keyword to the class!\n    {\n        [ObservableSetting(\"Volume\")]   // The \"Volume\" here is the key of the setting in storage\n        private readonly double volume = 0.75;  // This field is used as the default setting value\n    }\n    ```\n\n    It will generate a partial class:\n\n    ```csharp\n    public partial class SettingsService : INotifyPropertyChanged\n    {\n        // You can bind to \"Volume\" in XAML\n        public event PropertyChangedEventHandler? PropertyChanged;\n\n        // When the setting \"Volume\" changes, this event will be raised\n        public event EventHandler\u003cSettingValueChangedEventArgs\u003cdouble\u003e\u003e? VolumeChanged;\n\n        // Strong typed \"Volume\" property to read and write setting in storage\n        public double Volume \n        {\n            get { ... } // Read setting from storage\n            set { ... } // Write setting to storage\n        }\n    }\n    ```\n\n3.  Now you can use the generated class to read and write settings:\n\n    ```csharp\n    SettingsService settingsService = new SettingsService();\n\n    // Handle setting value changed events\n    settingsService.VolumeChanged += (s, e) =\u003e \n    {\n        Debug.WriteLine($\"Volume changed from {e.OldValue} to {e.NewValue}\");\n    }\n\n    Volume volume = settingsService.Volume; // Read settings from storage\n\n    volume = volume / 2;\n\n    settingsService.Volume = volume // Write settings to storage\n    ```\n\n\n# Details\n\n## How does the generated class look like?\n\nBasically like this:\n\n```csharp\npublic partial class SettingsService : INotifyPropertyChanged\n{\n    private IPropertySet LocalSettings =\u003e Windows.Storage.ApplicationData.Current.LocalSettings.Values;\n\n    public event PropertyChangedEventHandler? PropertyChanged;\n\n    public event EventHandler\u003cSettingValueChangedEventArgs\u003cdouble\u003e\u003e? VolumeChanged;\n        \n    public double Volume\n    {\n        get\n        {\n            if (LocalSettings.TryGetValue(\"Volume\", out object? settingObject))\n            {\n                if (settingObject is double settingValue)\n                {\n                    return settingValue;\n                }\n            }\n            return volume;\n        }\n        set\n        {\n            double oldValue = Volume;\n            if (!EqualityComparer\u003cdouble\u003e.Default.Equals(oldValue, value))\n            {\n                LocalSettings[\"Volume\"] = value;\n                PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(\"Volume\"));\n                VolumeChanged?.Invoke(this, new SettingValueChangedEventArgs\u003cdouble\u003e(oldValue, value));\n            }\n        }\n    }\n}\n```\n\n## Provide an explicit setting key\n\n- It's highly recommended to provide an explicit `settingKey` to the `[ObservableSetting]` attribute.\n\n  ```csharp\n  [ObservableSetting(\"UserEmail\")]\n  private readonly string userEmail = \"\";\n  ```\n\n- If you don't, the Pascal form of the attributed field name will be used (same as the generated property name). \n\n  ```csharp\n  [ObservableSetting] // Setting key is \"UserEmail\"\n  private readonly string userEmail = \"\";\n  ```\n  \n  ⚠ 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!\n\n## How are the settings stored?\n\n[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`.\n\n- If the type of the setting to save is one of these \"native\" setting types, it will be directly stored in storage.\n\n- Otherwise, it will be serialized as JSON with `System.Text.Json` and saved as `string`.\n\n## Setting size limit\n\nAccording to the [official documents](https://learn.microsoft.com/en-us/uwp/api/windows.storage.applicationdata.localsettings#remarks):\n\n- Each setting key can be 255 characters in length at most.\n- Each setting can be up to 8K bytes in size.\n\n# Acknowledgements\n\nThis project is inspired by:\n- https://github.com/joseangelmt/ObservableSettings\n- [Microsoft MVVM Toolkit Source Generators](https://github.com/CommunityToolkit/dotnet)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonwei512%2Fwinui-observablesettings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasonwei512%2Fwinui-observablesettings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonwei512%2Fwinui-observablesettings/lists"}