StageKit 0.1.2

StageKit

StageKit is a lightweight .NET application infrastructure library for JSON settings files, observable settings objects, crash report capture, application runtime metadata, and unhandled exception handling.

Features

• Singleton JSON settings files with lazy load, manual save, AutoSave, and debounced save support
• Observable settings base classes powered by CommunityToolkit.Mvvm
• Collection-backed settings files using ObservableList<T> with ItemsView for synchronized binding
• Save hooks through BeforeSave() and AfterSave()
• Pending debounce tracking with timeout-aware wait support
• Serializable crash reports with exception chains, stack traces, runtime information, and process stats
• AppDomain and task scheduler unhandled exception helpers
• Panic-save support for registered ISavable settings before forced process exit
• Configurable profile, config, and log paths
• Small application "birthday" helpers for version/about screens

Install

dotnet add package StageKit

Requirements

• .NET 8 or newer
• C# latest language version

Quick Start

Configure StageKit during application startup:

using Microsoft.Extensions.Logging;
using StageKit;

ApplicationKit.ApplicationName = "MyApp";
ApplicationKit.ApplicationArgs = args;
ApplicationKit.Logger = logger;
ApplicationKit.UiFrameworkInfo = $"Avalonia {typeof(AvaloniaObject).Assembly.GetName().Version!.ToString(3)}";
ApplicationKit.Birth = DateTime.SpecifyKind(new DateTime(2026, 1, 1), DateTimeKind.Utc);

UnhandledExceptions.RegisterAppDomainUnhandledException();
UnhandledExceptions.RegisterTaskSchedulerUnobservedTaskException();

CrashReportsFile.IsEnabled = true;

Settings Files

Create a root settings file by inheriting from RootSettingsFile<T>:

using StageKit;

public partial class AppSettings : RootSettingsFile<AppSettings>
{
    [ObservableProperty]
    public partial string Theme { get; set; } = "System";

    [ObservableProperty]
    public partial string ThemeColor { get; set; } = "Blue";

    [ObservableProperty]
    public partial bool EnableCrashReporting { get; set; } = true;

    [ObservableProperty]
    public partial long LastRunTimestamp { get; set; }

    public AppSettings()
    {
        AutoSave = true;
    }
}

Enable AutoSave when property changes should save automatically:

var settings = AppSettings.Instance;
settings.AutoSave = true;
settings.Theme = "Dark";

AutoSave defaults to false. It starts reacting only after the settings object is loaded, so property changes caused by JSON hydration or OnLoaded(...) do not rewrite the file during startup.

Keep AutoSave disabled when you prefer manual control:

AppSettings.Instance.AutoSave = false;

AppSettings.SaveInstance();

Use debounced save APIs when you want to batch rapid changes:

settings.DebouncedSave();

var saved = await settings.WaitForDebouncedSaveAsync(
    TimeSpan.FromSeconds(5),
    cancellationToken);

if (!saved)
{
    // timeout elapsed while the save was still pending
}

Save() cancels any pending debounced save before writing. CancelDebouncedSave() cancels a scheduled save without writing.

By default, settings are stored under:

ApplicationKit.ConfigPath

Override DirectoryPath or set ApplicationKit.ProfilePath to customize storage.

If a settings file fails to deserialize on load (corrupt JSON, schema mismatch), StageKit renames it to <file>.corrupt-<timestampUtc> and falls back to a fresh instance. Original data is preserved on disk for inspection or recovery.

Collection Settings

Use RootCollectionFile<T, TO> when a settings file is mainly a list:

using StageKit;

public sealed class RecentFiles : RootCollectionFile<RecentFiles, string>
{
    public override string FileName => "recent-files.json";

    public override int TrimCollectionWhenExceeding => 20;

    public override CollectionSide TrimCollectionSide => CollectionSide.Head;
}

RecentFiles.Instance.Add(@"C:\work\project.txt");
RecentFiles.SaveInstance();

RootCollectionFile<T, TO> exposes Items as an ObservableList<TO> and ItemsView as a synchronized view for UI binding. Override TrackItemsWithChangeNotification when collection items implement INotifyPropertyChanged and item property changes should mark the file dirty and trigger AutoSave; keep it disabled for immutable items or very large collections.

Observable Objects

SubSettings is based on CommunityToolkit.Mvvm.ComponentModel.ObservableObject:

using StageKit;

public sealed class ViewState : SubSettings
{
    private bool _isBusy;

    public bool IsBusy
    {
        get => _isBusy;
        set => SetProperty(ref _isBusy, value);
    }
}

Classes deriving from SubSettings, RootSettingsFile<T>, or RootCollectionFile<T, TO> can use CommunityToolkit's [ObservableProperty] generator:

using CommunityToolkit.Mvvm.ComponentModel;
using StageKit;

public sealed partial class AppSettings : RootSettingsFile<AppSettings>
{
    public override string FileName => "appsettings.json";

    [ObservableProperty]
    private string _theme = "System";
}

StageKit references CommunityToolkit.Mvvm, but if your app uses generator attributes such as [ObservableProperty], reference CommunityToolkit.Mvvm directly in that app too so the analyzer/source generator runs in the consuming project.

Crash Reports

Create crash reports directly:

try
{
    RunApplication();
}
catch (Exception ex)
{
    var report = new CrashReport(ex, "Startup");
    Console.WriteLine(report.FormattedMessage);
}

StageKit can also capture unhandled exceptions:

UnhandledExceptions.HandleCrashReport = report =>
{
    Console.WriteLine(report.FormattedMessage);
    return true;
};

If CrashReportsFile.IsEnabled is true, fatal unhandled exceptions are added to CrashReportsFile.Instance.

Register settings that should be saved before StageKit forces process exit after a fatal exception:

UnhandledExceptions.SettingsFilesToSaveBeforeCrash.Add(AppSettings.Instance);

SettingsFilesToSaveBeforeCrash is a HashSet<StageKit.Interfaces.ISavable>, so any type implementing ISavable can participate.

Ignoring Known Safe Exceptions

Ignore by exception type:

UnhandledExceptions.IgnoredExceptionList.Add(typeof(OperationCanceledException));

Ignore by message fragment:

UnhandledExceptions.IgnoredExceptionMessages.Add("known benign message");

Avalonia DBus noise can be ignored with:

UnhandledExceptions.IgnoreAvaloniaSafeExceptions();

Application Birthday Helpers

ApplicationKit.Birth = DateTime.SpecifyKind(new DateTime(2026, 1, 1), DateTimeKind.Utc);

Console.WriteLine(ApplicationKit.YearsOld);
Console.WriteLine(ApplicationKit.AgeShortStr);
Console.WriteLine(ApplicationKit.IsBirthday);

Runtime duration since library initialization is available through:

Console.WriteLine(ApplicationKit.RuntimeElapsed);

Demo

See StageKit.Demo/Program.cs for a runnable console demo covering startup configuration, Serilog integration, AutoSave settings, collection settings, panic-save registration, crash report launch handling, and debounced save waiting.

Run it with:

dotnet run --project StageKit.Demo/StageKit.Demo.csproj

Development

Restore, build, and test:

dotnet restore
dotnet build
dotnet test

Security

Please report vulnerabilities privately. See SECURITY.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

StageKit is licensed under the MIT License.