ktsu.AppDataStorage 1.16.36

Prefix Reserved
.NET 7.0 This package targets .NET 7.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package ktsu.AppDataStorage --version 1.16.36
                    


                    

                
NuGet\Install-Package ktsu.AppDataStorage -Version 1.16.36
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="ktsu.AppDataStorage" Version="1.16.36" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="ktsu.AppDataStorage" Version="1.16.36" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="ktsu.AppDataStorage" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add ktsu.AppDataStorage --version 1.16.36
                    


                    

                
#r "nuget: ktsu.AppDataStorage, 1.16.36"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package ktsu.AppDataStorage@1.16.36
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=ktsu.AppDataStorage&version=1.16.36
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=ktsu.AppDataStorage&version=1.16.36
                    


                            Install as a Cake Tool

ktsu.AppDataStorage

A .NET library for simple, persistent application data management with JSON serialization.

License NuGet Version NuGet Version NuGet Downloads GitHub commit activity GitHub contributors GitHub Actions Workflow Status

Introduction

ktsu.AppDataStorage is a .NET library designed to simplify the process of persisting application data. It stores configuration or state data as JSON files in the user's application data folder, with built-in safety mechanisms like automatic backups, debounced saves, and thread-safe operations. The library provides a singleton-like access pattern and supports custom subdirectories and file names for organizing data.

Features

  • Easy-to-use API: Inherit from AppData<T> and get automatic JSON persistence with LoadOrCreate(), Save(), and Get().
  • Automatic Backup: Creates backup files before overwriting to prevent data loss, with timestamped collision handling.
  • Safe Write Pattern: Writes to a temporary file first, then atomically replaces the original to avoid corruption.
  • Debounced Saves: QueueSave() and SaveIfRequired() prevent frequent file writes with a 3-second debounce window.
  • Thread-Safe Operations: All file operations are synchronized with lock objects (uses Lock type on .NET 9+, object on earlier versions).
  • Singleton Access: Get() provides lazy-initialized, singleton-like access to your app data instance.
  • Custom Storage Locations: Support for custom subdirectories and file names via LoadOrCreate() overloads.
  • File System Abstraction: Uses System.IO.Abstractions for easy unit testing with mock file systems.
  • Corrupt File Recovery: Automatically falls back to backup files when the main data file is corrupt or missing.
  • Dispose-on-Exit: Registers for process exit to ensure queued saves are flushed before the application terminates.

Installation

Package Manager Console

Install-Package ktsu.AppDataStorage

.NET CLI

dotnet add package ktsu.AppDataStorage

Package Reference

<PackageReference Include="ktsu.AppDataStorage" Version="x.y.z" />

Usage Examples

Basic Example

Create a class that inherits from AppData<T>, where T is your custom data type.

using ktsu.AppDataStorage;

public class MySettings : AppData<MySettings>
{
    public string Theme { get; set; } = "light";
    public int FontSize { get; set; } = 14;
    public bool AutoSave { get; set; } = true;
}

// Load existing data or create a new instance
var settings = MySettings.LoadOrCreate();
Console.WriteLine(settings.Theme);    // "light"
Console.WriteLine(settings.FontSize); // 14

Accessing the Singleton Instance

The Get() method provides a lazy-initialized singleton instance, automatically calling LoadOrCreate() on first access.

using ktsu.AppDataStorage;

// Access the singleton from anywhere in your application
var settings = MySettings.Get();
settings.Theme = "dark";
settings.Save();

// Same instance returned every time
var sameSettings = MySettings.Get();
Console.WriteLine(sameSettings.Theme); // "dark"

Saving Data

Modify properties and call Save() to persist changes immediately.

using ktsu.AppDataStorage;

var settings = MySettings.Get();
settings.Theme = "dark";
settings.FontSize = 16;
settings.Save();

Custom Storage Location

Use overloads of LoadOrCreate() to store data in subdirectories or with custom file names.

using ktsu.AppDataStorage;
using ktsu.Semantics.Paths;

// Store in a subdirectory
var profileData = MySettings.LoadOrCreate(RelativeDirectoryPath.Create("profiles"));

// Store with a custom file name
var customData = MySettings.LoadOrCreate(FileName.Create("user_preferences.json"));

// Both subdirectory and custom file name
var specificData = MySettings.LoadOrCreate(
    RelativeDirectoryPath.Create("profiles"),
    FileName.Create("admin_settings.json"));

Advanced Usage

Queued and Debounced Saving

For scenarios with frequent updates (e.g., UI-driven changes), use QueueSave() to schedule a save that is debounced with a 3-second threshold. Call SaveIfRequired() periodically (e.g., in a game loop or timer) to flush queued saves.

using ktsu.AppDataStorage;

var settings = MySettings.Get();
settings.Theme = "dark";
settings.QueueSave();  // Schedules a save

// Later, in your update loop or timer:
settings.SaveIfRequired();  // Saves only if 3+ seconds have elapsed since QueueSave

// Or use the static convenience methods:
MySettings.QueueSave();
MySettings.SaveIfRequired();

Queued saves are also automatically flushed when the AppData<T> instance is disposed or when the process exits.

Testing with Mock File Systems

The library supports System.IO.Abstractions for testability. Configure a mock file system in your tests:

using System.IO.Abstractions.TestingHelpers;
using ktsu.AppDataStorage;

// In test setup - each thread gets its own isolated instance
AppData.ConfigureForTesting(() => new MockFileSystem());

// Run your tests...
var data = MySettings.LoadOrCreate();
data.Theme = "test";
data.Save();

// In test teardown
AppData.ResetFileSystem();

Directory and File Paths

Data is stored in a directory unique to the current application domain under the user's %APPDATA% folder. File names are derived from the class name in snake_case.

using ktsu.AppDataStorage;

// View the storage path
Console.WriteLine(AppData.Path);
// e.g., C:\Users\{user}\AppData\Roaming\{AppDomainName}

// File name is automatically generated from the class name
// MySettings -> my_settings.json

API Reference

AppData Static Class

Provides static helper methods and properties for managing application data storage.

Properties
Name Type Description
Path AbsoluteDirectoryPath The path where persistent data is stored for this application
Methods
Name Return Type Description
WriteText<T>(T appData, string text) void Writes text to an app data file using a safe write pattern
ReadText<T>(T appData) string Reads text from an app data file, falling back to backup if missing
QueueSave<T>(this T appData) void Extension method that queues a debounced save operation
SaveIfRequired<T>(this T appData) void Extension method that saves if the debounce threshold has elapsed
ConfigureForTesting(Func<IFileSystem>) void Configures a mock file system factory for unit testing
ResetFileSystem() void Resets the file system to the default implementation after testing

AppData<T> Generic Abstract Class

Base class for app data storage. Inherit from this class to create persistable data types.

Type Constraints

T : AppData<T>, IDisposable, new()

Instance and Static Methods
Name Return Type Description
Get() T Gets the lazy-initialized singleton instance of the app data
LoadOrCreate() T Loads app data from file or creates a new instance if none exists
LoadOrCreate(RelativeDirectoryPath?) T Loads or creates with a custom subdirectory
LoadOrCreate(FileName?) T Loads or creates with a custom file name
LoadOrCreate(RelativeDirectoryPath?, FileName?) T Loads or creates with both custom subdirectory and file name
Save() void Serializes and saves the app data to its JSON file
QueueSave() void Queues a debounced save for the singleton instance
SaveIfRequired() void Saves the singleton instance if the debounce threshold has elapsed
Dispose() void Disposes the instance, flushing any queued saves

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on ktsu.AppDataStorage:

Package Downloads
ktsu.SingleAppInstance

A lightweight .NET library that ensures only one instance of an application is running at a time. Uses a JSON-serialized PID file with multi-attribute process verification (PID, name, start time, executable path) for accurate instance detection, built-in race condition handling for simultaneous startups, and backward compatibility with legacy PID formats. Supports .NET 10.0 through .NET Standard 2.0.
ktsu.GitIntegration

Git Integration
ktsu.BlastMerge

Cross-repository file synchronization tool that uses intelligent iterative merging to unify multiple file versions with interactive conflict resolution. Features include batch processing with custom search paths and exclusion patterns, parallel file hashing for performance, persistent command history, and comprehensive automation capabilities for multi-repository workflows. Supports advanced diff visualization, pattern-based file discovery, and discrete processing phases with real-time progress reporting.
ktsu.KtsuTools.Core

KtsuTools is a unified developer tools suite that consolidates multiple ktsu-dev utilities into a single CLI application with consistent UX powered by Spectre.Console.
ktsu.KtsuTools.Merge

KtsuTools is a unified developer tools suite that consolidates multiple ktsu-dev utilities into a single CLI application with consistent UX powered by Spectre.Console.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.16.37 0 8/18/2026
1.16.36 78 8/17/2026
1.16.35 105 8/17/2026
1.16.34 290 8/11/2026
1.16.33 769 7/8/2026
1.16.32 287 7/7/2026
1.16.31 235 7/6/2026
1.16.30 236 7/3/2026
1.16.29 261 7/2/2026
1.16.28 244 7/1/2026
1.16.27 255 6/30/2026
1.16.26 268 6/29/2026
1.16.25 272 6/28/2026
1.16.24 189 6/28/2026
1.16.23 620 6/12/2026
1.16.22 246 6/12/2026
1.16.21 614 6/8/2026
1.16.20 320 6/4/2026
1.16.19 251 6/2/2026
1.16.18 515 5/22/2026
Loading failed

## v1.16.36 (patch)

Changes since v1.16.35:

- Bump the ktsu group with 2 updates ([@dependabot[bot]](https://github.com/dependabot[bot]))