Local.Settings.Json

Simple C# library to load and persist JSON settings using strongly-typed classes. Designed for local disk persistence in Desktop and Mobile environments.

NOTE: not intended for Web API or Cloud contexts.

Features

• Strongly-typed settings: Map JSON files directly to C# classes.
• Local Persistence: Simplified Read/Write operations to the local file system.
• Change Notifications: Event handling support to react when settings are updated.
• Flexible Storage: Define custom paths or use the default AppData/ApplicationName directory.
• Lightweight: Minimal overhead.

Instalation

dotnet add package LocalSettingsJson

Usage

Define your Settings

Your class must inherit from SettingsBase and have a parameterless constructor.

// Must inherit from SettingsBase
public class TestSettings : SettingsBase
{
    public string Name { get; set; }
    public int Age { get; set; }
}

If you want to have granular control over change notifications, you can implement properties strictly (using the helper) or manually. In both cases, the PropertyChanged event will be triggered.

public class TestSettings : SettingsBase
{
    // Basic properties
    // ...
    
    // Advanced properties
    private string _themeColor = "Dark";

    public bool IsFullScreen
    {
        get => field;
        // Strict: Updates the field and triggers PropertyChanged automatically
        set => SetProperty(ref field, value);
    }

    public string ThemeColor
    {
        get => _themeColor;
        set
        {
            // ...
            _themeColor = value;
            // ...

            // Manual: Notifies subscribers that this specific property changed
            OnPropertyChanged(nameof(ThemeColor));
        }
    }
}

📤 Loading Settings

// Default path: ~/AppData/Local/YourAppName/settings.json...
var settings = SettingsStorage.Load<TestSettings>();

// Custom absolute path
var settings = SettingsStorage.LoadOrDefault<TestSettings>("C:/path/to/config.json");

// Safe loading with error handling
TestSettings settings;
var result = SettingsStorage.TryLoad<TestSettings>("C:/path/to/config.json");
if (result.Success) 
{
    settings = result.Instance;
}
//...

👀 Read & Access

Once loaded, you access your properties directly from the instance.

// Access properties directly
Console.WriteLine($"Current Name: {settings.Name}");
Console.WriteLine($"Current Age: {settings.Age}");

// You can also check the current file path being used
Console.WriteLine($"Config file located at: {settings.FilePath}");

💽 Persisting Changes

The library allows for both manual and automated disk writes.

// Manual Save
settings.Name = "John Doe";
SettingsStorage.Save(settings);

// Auto Save
settings.Update(s => 
{
    s.Name = "Jane Doe";
    s.Age = 25;
});

⚡ Events and Error Handling

Subscribe to these to handle UI updates or I/O errors.

// Fires on any property change triggered by SetProperty or OnPropertyChanged
settings.PropertyChanged += (s, e) => Console.WriteLine($"Property: {e.PropertyName}");

// Fires on any property change in memory
settings.SettingsChanged += (s, e) => Console.WriteLine("Settings changed.");

// Confirmation after a successful write to disk
settings.SettingsSaved += (s, e) => Console.WriteLine("Settings saved successfully.");

// Catch and handle Save errors (e.g., permission issues)
settings.SavingErrorOcurred += (s, e) =>
{
    Console.WriteLine($"Error: {e.Exception.Message}");

    // (Optional) Prevents the exception from bubbling up
    e.Handled = true;
};

🤝 Contributing

PRs are welcome.

📄 License

MIT ©BracoZS