ShadowObservableConfig 0.6.0

✨ ShadowObservableConfig

一个为 WinUI 3 设计的响应式配置文件管理库，通过源代码生成器自动生成配置类，支持 YAML/JSON 格式配置文件，提供完整的 MVVM 数据绑定支持。

🌟 特性

• 🚀 源代码生成器：自动生成配置类，减少样板代码
• 📱 WinUI 3 支持：为 WinUI 3 应用程序优化
• 🔄 响应式配置：支持 INotifyPropertyChanged 和 INotifyCollectionChanged
• 📄 YAML 支持：YAML 配置文件支持(YamlDotNet)
• 📄 JSON 支持：JSON 配置文件支持(Newtonsoft.Json)
• 🎯 类型安全：编译时类型检查，避免运行时错误
• 🔧 自动保存：配置更改时自动保存到文件
• 📦 嵌套配置：支持复杂的嵌套配置结构
• 🎨 数据绑定：完美支持 WinUI 数据绑定

📦 安装

YAML 支持

<PackageReference Include="ShadowObservableConfig.Yaml" Version="0.6.0" />

// In App.xaml.cs
ShadowObservableConfig.GlobalSetting.Init(ApplicationData.Current.LocalFolder.Path,
[
    new ShadowObservableConfig.Yaml.YamlConfigLoader()
]);

YAML 支持

<PackageReference Include="ShadowObservableConfig.Json" Version="0.6.0" />

// In App.xaml.cs
ShadowObservableConfig.GlobalSetting.Init(ApplicationData.Current.LocalFolder.Path,
[
    new ShadowObservableConfig.Json.JsonConfigLoader()
]);

🚀 快速开始

FileExt 根据安装的库可选: .yaml 或 .json

1. 创建配置类(以yaml为例子)

using ShadowObservableConfig.Attributes;
using System.Collections.ObjectModel;

[ObservableConfig(FileName = "app_config", FileExt = ".yaml", DirPath = "config", Description = "应用程序配置", Version = "1.0.0")]
public partial class AppConfig
{
    [ObservableConfigProperty(Name = "AppName", Description = "应用程序名称")]
    private string _appName = "My App";

    [ObservableConfigProperty(Name = "IsEnabled", Description = "是否启用")]
    private bool _isEnabled = true;

    [ObservableConfigProperty(Name = "MaxRetryCount", Description = "最大重试次数")]
    private int _maxRetryCount = 3;

    [ObservableConfigProperty(Name = "Settings", Description = "应用设置")]
    private AppSettings _settings = new();

    [ObservableConfigProperty(Name = "Features", Description = "功能列表")]
    private ObservableCollection<string> _features = new();
}

[ObservableConfig(Description = "应用设置", Version = "1.0.0")]
public partial class AppSettings
{
    [ObservableConfigProperty(Name = "Theme", Description = "主题")]
    private string _theme = "Light";

    [ObservableConfigProperty(Name = "Language", Description = "语言")]
    private string _language = "zh-CN";
}

2. 在 WinUI 3 中使用(以yaml为例子)

// App.xaml.cs
public App()
{
    InitializeComponent();
    ShadowObservableConfig.GlobalSetting.Init(ApplicationData.Current.LocalFolder.Path,
    [
        new ShadowObservableConfig.Yaml.YamlConfigLoader()
    ]);
}

public sealed partial class MainPage : Page
{
    public AppConfig ViewModel { get; } = AppConfig.Load();

    public MainPage()
    {
        this.InitializeComponent();
        ViewModel.ConfigChanged += OnConfigChanged;
    }

    private void OnConfigChanged(object? sender, ConfigChangedEventArgs e)
    {
        Debug.WriteLine($"配置项 '{e.FullPropertyPath}' 已更改: {e.OldValue} -> {e.NewValue}");
    }
}

3. XAML 数据绑定

<Page x:Class="MyApp.MainPage">
    <StackPanel>
        <TextBox Header="应用程序名称" 
                 Text="{x:Bind ViewModel.AppName, Mode=TwoWay}" />
        
        <CheckBox Content="启用应用程序" 
                  IsChecked="{x:Bind ViewModel.IsEnabled, Mode=TwoWay}" />
        
        <NumberBox Header="最大重试次数" 
                   Value="{x:Bind ViewModel.MaxRetryCount, Mode=TwoWay}" />
        
        <ComboBox Header="主题" 
                  SelectedItem="{x:Bind ViewModel.Settings.Theme, Mode=TwoWay}">
            <ComboBoxItem Content="Light" />
            <ComboBoxItem Content="Dark" />
        </ComboBox>
    </StackPanel>
</Page>

📚 详细文档

属性说明

ObservableConfigAttribute

• FileName: 配置文件名（不含扩展名）不填该项说明当前类是内部类
• FileExt: 配置文件扩展名
• DirPath: 配置文件目录（默认为 "config"）
• Description: 配置描述
• Version: 配置版本

ObservableConfigPropertyAttribute

• Name: 属性在配置文件中的名称
• Description: 属性描述
• Alias: 属性别名(只在yaml有效)
• AutoSave: 是否自动保存（默认为 true）

支持的数据类型

• 基本类型：string, int, double, bool, DateTime等
• 枚举类型：任何 enum 类型
• 集合类型：ObservableCollection<T>
• 嵌套对象：其他标记了 [ObservableConfig] 的类

自动生成的方法

源代码生成器会自动为每个配置类生成：

• 公共属性访问器
• Load() 静态方法
• Save() 方法
• AfterConfigInit() 部分方法（可重写）

🔧 高级用法

自定义配置加载器

public class CustomConfigLoader : IConfigLoader
{
    public T Load<T>(string filePath) where T : class
    {
        // 自定义加载逻辑
        return JsonSerializer.Deserialize<T>(File.ReadAllText(filePath));
    }

    public void Save<T>(T config, string filePath) where T : class
    {
        // 自定义保存逻辑
        File.WriteAllText(filePath, JsonSerializer.Serialize(config, new JsonSerializerOptions { WriteIndented = true }));
    }
}

自定义结束记得在ShadowObservableConfig.GlobalSetting.Init里设置

配置初始化回调

[ObservableConfig(FileName = "my_config")]
public partial class MyConfig
{
    [ObservableConfigProperty(Name = "Value")]
    private string _value = "default";

    partial void AfterConfigInit()
    {
        // 配置加载完成后的初始化逻辑
        Console.WriteLine($"配置已加载: {Value}");
    }
}

🏗️ 项目结构

ShadowObservableConfig/
├── ShadowObservableConfig/              # 核心库
│   ├── BaseConfig.cs                    # 基础配置类
│   ├── Attributes/                      # 属性定义
│   └── Args/                           # 事件参数
├── ShadowObservableConfig.SourceGenerator/  # 源代码生成器
│   └── Generators/                     # 生成器实现
├── ShadowObservableConfig.Yaml/        # YAML 支持扩展
├── ShadowObservableConfig.Json/        # JSON 支持扩展
└── Config.WinUI/                       # WinUI 3 示例应用

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• YamlDotNet - YAML 序列化库
• Newtonsoft.Json - JSON 序列化库
• Microsoft.CodeAnalysis - 源代码分析 API
• WinUI 3 - 现代 Windows 应用框架

Made with ❤️ by kitUIN