ktsu.AppDataStorage 1.4.7

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package ktsu.AppDataStorage --version 1.4.7                

                    
                

            
NuGet\Install-Package ktsu.AppDataStorage -Version 1.4.7
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.4.7" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add ktsu.AppDataStorage --version 1.4.7                

                    
                

            
#r "nuget: ktsu.AppDataStorage, 1.4.7"
#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. 
// Install ktsu.AppDataStorage as a Cake Addin
#addin nuget:?package=ktsu.AppDataStorage&version=1.4.7

// Install ktsu.AppDataStorage as a Cake Tool
#tool nuget:?package=ktsu.AppDataStorage&version=1.4.7

ktsu.AppDataStorage

ktsu.AppDataStorage is a .NET library designed to simplify the process of managing application data. It facilitates saving and loading configuration or state data to the application's data folder, leveraging JSON serialization.

Features

  • Easy-to-use API: Intuitive methods for saving and loading data.
  • Automatic Backup: Backs up original files before overwriting to ensure data safety.
  • Custom Serialization Options: Uses System.Text.Json with support for custom converters.
  • File System Abstraction: Uses System.IO.Abstractions for easy unit testing and mocking.
  • Debounced Saves: Prevents frequent file writes to improve performance.
  • Support for Multiple Applications: Organizes data by application domain for isolation.
  • Static Instance Access: Provides easy access to a singleton-like instance for centralized data management.

Installation

Install the package via NuGet:

dotnet add package ktsu.AppDataStorage

Usage

Defining Your Application Data Class

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

public class MyAppData : AppData<MyAppData>
{
    public string Setting1 { get; set; } = "hello";
    public int Setting2 { get; set; } = 12;
}

Loading Data

Load existing data or create a new instance if no data file exists using LoadOrCreate.

var data = MyAppData.LoadOrCreate();
Console.WriteLine(data.Setting1);
Console.WriteLine(data.Setting2);

// Output:
// hello
// 12

Accessing the Static Instance

The AppData<T> class provides a static instance through the Get method, which ensures a single, easily accessible instance is available throughout your application:

var data = MyAppData.Get();
Console.WriteLine(data.Setting1);

The static instance is initialized automatically and matches the instance returned by LoadOrCreate. Changes to the static instance are persistent once saved:

var data = MyAppData.Get();
data.Setting1 = "new value";
data.Save();

var sameData = MyAppData.Get();
Console.WriteLine(sameData.Setting1);

// Output:
// new value

This functionality is useful for applications where centralized access to app data is required without repeatedly loading or instantiating objects.

Saving Data

Modify properties and save the data using the Save method.

var data = MyAppData.Get();
data.Setting1 = "goodbye";
data.Setting2 = 42;
data.Save();

var reloadedData = MyAppData.Get();
Console.WriteLine(reloadedData.Setting1);
Console.WriteLine(reloadedData.Setting2);

// Output:
// goodbye
// 42

Queued and Debounced Saving

For scenarios with frequent updates, you can queue save operations using QueueSave, which automatically debounces writes to avoid frequent file system operations.

MyAppData.QueueSave();  // Schedules a save
MyAppData.SaveIfRequired();  // Performs the save if the debounce threshold is exceeded

Writing and Reading Arbitrary Text Files

Write and read arbitrary files in the application's data folder using the static AppData class.

Write Text:
AppData.WriteText("example.txt".As<FileName>(), "Hello, AppData!");
Read Text:
string content = AppData.ReadText("example.txt".As<FileName>());
Console.WriteLine(content);

// Output:
// Hello, AppData!

Customizing Serialization

Serialization behavior can be customized using JsonSerializerOptions. By default, the library uses:

  • Indented JSON for readability.
  • ReferenceHandler.Preserve for circular references.
  • Converters such as JsonStringEnumConverter and ToStringJsonConverter.

Directory and File Paths

Data is stored in a directory unique to the current application domain:

var appDataPath = AppData.Path;
Console.WriteLine($"App Data Path: {appDataPath}");

Advanced Features

Backup and Temporary Files

Backup and temporary files are automatically managed during save operations to ensure data integrity:

  • Backup file extension: .bk
  • Temporary file extension: .tmp

File System Abstraction

The library uses System.IO.Abstractions, allowing you to inject a custom file system implementation for testing.

Contributing

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

License

This project is licensed under the MIT License.

Product Compatible and additional computed target framework versions.
.NET 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

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

Package Downloads
ktsu.CredentialCache

CredentialCache
ktsu.GitIntegration

Git Integration

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.4.7 142 1/3/2025
1.4.7-pre.6 30 1/7/2025
1.4.7-pre.5 38 1/5/2025
1.4.7-pre.4 58 1/3/2025
1.4.7-pre.3 35 1/3/2025
1.4.7-pre.2 43 1/3/2025
1.4.7-pre.1 46 1/3/2025
1.4.6 91 1/2/2025
1.4.5 84 1/2/2025
1.4.4 73 1/2/2025
1.4.3 71 1/2/2025
1.4.2 76 1/2/2025
1.4.1 72 1/2/2025
1.4.0 73 1/2/2025
1.3.16 163 1/2/2025
1.3.16-pre.6 47 1/2/2025
1.3.16-pre.5 66 12/31/2024
1.3.16-pre.4 41 12/30/2024
1.3.16-pre.3 43 12/29/2024
1.3.16-pre.2 39 12/28/2024
1.3.16-pre.1 39 12/27/2024
1.3.15 188 12/27/2024
1.3.14 75 12/27/2024
1.3.13-pre.1 41 12/27/2024
1.3.12-pre.1 39 12/27/2024
1.3.11-pre.1 42 12/27/2024
1.3.10 116 12/26/2024
1.3.10-pre.1 39 12/27/2024
1.3.9 117 12/26/2024
1.3.8 75 12/26/2024
1.3.7 71 12/26/2024
1.3.6 70 12/26/2024
1.3.5 82 12/26/2024
1.3.4 84 12/26/2024
1.3.3 123 12/25/2024
1.3.2 236 12/23/2024
1.3.1 97 12/23/2024
1.3.0 70 12/23/2024
1.2.4 69 12/23/2024
1.2.3 123 12/22/2024
1.2.2 77 12/22/2024
1.2.1 95 12/22/2024
1.2.0 79 12/22/2024
1.1.57 136 12/19/2024
1.1.56 126 12/19/2024
1.1.55 157 12/17/2024
1.1.54 131 12/16/2024
1.1.53 261 12/9/2024
1.1.52 163 12/6/2024
1.1.51 177 12/5/2024
1.1.50 110 12/5/2024
1.1.49 125 12/4/2024
1.1.48 165 12/2/2024
1.1.47 81 12/2/2024
1.1.46 103 12/2/2024
1.1.45 95 12/2/2024
1.1.44 95 12/2/2024
1.1.43 108 12/1/2024
1.1.42 92 12/1/2024
1.1.41 163 12/1/2024
1.1.40 99 12/1/2024
1.1.39 129 11/30/2024
1.1.38 91 11/30/2024
1.1.37 107 11/29/2024
1.1.36 130 11/28/2024
1.1.35 137 11/27/2024
1.1.34 131 11/26/2024
1.1.33 231 11/20/2024
1.1.32 128 11/19/2024
1.1.31 152 11/15/2024
1.1.30 116 11/14/2024
1.1.29 135 11/13/2024
1.1.28 127 11/12/2024
1.1.27 136 11/11/2024
1.1.26 126 11/8/2024
1.1.25 132 11/6/2024
1.1.24 126 11/5/2024
1.1.23 135 11/4/2024
1.1.22 237 11/2/2024
1.1.21 97 11/1/2024
1.1.20 378 10/18/2024
1.1.19 319 10/9/2024
1.1.18 108 10/8/2024
1.1.17 96 10/7/2024
1.1.16 111 10/4/2024
1.1.15 198 9/25/2024
1.1.14 117 9/24/2024
1.1.13 108 9/23/2024
1.1.12 119 9/20/2024
1.1.11 119 9/19/2024
1.1.10 113 9/19/2024
1.1.9 81 9/19/2024
1.1.8 117 9/19/2024
1.1.7 158 9/18/2024
1.1.6 106 9/18/2024
1.1.5 97 9/18/2024
1.1.4 110 9/18/2024
1.1.3 153 9/14/2024
1.1.2 124 9/14/2024

## v1.4.6 (patch)

Changes since v1.4.5:

- Fix typo in variable name in make-changelog.ps1 ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.4.5 (patch)

Changes since v1.4.4:

- Fix typo in variable name and remove unnecessary logging in make-changelog.ps1 ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.4.4 (patch)

Changes since v1.4.3:

- Enhance changelog formatting by adding additional line breaks for improved readability ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.4.3 (patch)

Changes since v1.4.2:

- Add logging for note generation in MakeNotesForRange function ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.4.2 (patch)

Changes since v1.4.1:

- Add changelog entry for changes since the specified tag in MakeNotesForRange function ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.4.1 (patch)

Changes since v1.4.0:

- Refactor version type checks in MakeNotesForRange function and add exclusion for PowerShell files in make-version.ps1 ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.4.0 (minor)

Changes since v1.3.0:

- Add VERSION_TYPE variable to MakeNotesForRange function ([@matt-edmondson](https://github.com/matt-edmondson))
- Fix license ([@matt-edmondson](https://github.com/matt-edmondson))
- Fix range check in MakeNotesForRange function to handle additional version format ([@matt-edmondson](https://github.com/matt-edmondson))
- Fix regex for bot commit exclusion patterns in dotnet workflow ([@matt-edmondson](https://github.com/matt-edmondson))
- Fix syntax error in make-license.ps1 command in dotnet.yml ([@matt-edmondson](https://github.com/matt-edmondson))
- Modularize PowerShell scripts in dotnet.yml ([@matt-edmondson](https://github.com/matt-edmondson))
- Move IS_PRERELEASE assignment to where its actually gonna work ([@matt-edmondson](https://github.com/matt-edmondson))
- Move shared workflow into local workflow ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor bot commit exclusion patterns in dotnet workflow for case-insensitivity ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor bot commit exclusion patterns in dotnet workflow for improved clarity and case-insensitivity ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor exclusion patterns in dotnet workflow for improved clarity and consistency ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor exclusion patterns in dotnet workflow to simplify bot commit filtering ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor scripts and update workflow parameters ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove URL escaping from workflow and adjust environment variable output ([@matt-edmondson](https://github.com/matt-edmondson))
- Renamed metadata files ([@matt-edmondson](https://github.com/matt-edmondson))
- Replace LICENSE file with LICENSE.md ([@matt-edmondson](https://github.com/matt-edmondson))
- Sort git tags when retrieving the last released version in dotnet workflow ([@matt-edmondson](https://github.com/matt-edmondson))
- Update .mailmap for user and bot email consistency ([@matt-edmondson](https://github.com/matt-edmondson))
- Update .NET workflow to trigger on main and develop branches ([@matt-edmondson](https://github.com/matt-edmondson))
- Update exclusion pattern for hidden files in dotnet workflow ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.16 (patch)

Changes since v1.3.15:

- Fix syntax error in make-license.ps1 command in dotnet.yml ([@matt-edmondson](https://github.com/matt-edmondson))
- Modularize PowerShell scripts in dotnet.yml ([@matt-edmondson](https://github.com/matt-edmondson))
- Update .mailmap for user and bot email consistency ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.15 (patch)

Changes since v1.3.14:

- Move IS_PRERELEASE assignment to where its actually gonna work ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.14 (patch)

Changes since v1.3.13-pre.1:

- Refactor bot commit exclusion patterns in dotnet workflow for improved clarity and case-insensitivity ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.13-pre.1 (patch)

Changes since v1.3.12-pre.1:

- Fix regex for bot commit exclusion patterns in dotnet workflow ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor bot commit exclusion patterns in dotnet workflow for case-insensitivity ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.12-pre.1 (patch)

Changes since v1.3.11-pre.1:

- Refactor exclusion patterns in dotnet workflow to simplify bot commit filtering ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.11-pre.1 (patch)

Changes since v1.3.10:

- Move shared workflow into local workflow ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor exclusion patterns in dotnet workflow for improved clarity and consistency ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove URL escaping from workflow and adjust environment variable output ([@matt-edmondson](https://github.com/matt-edmondson))
- Renamed metadata files ([@matt-edmondson](https://github.com/matt-edmondson))
- Sort git tags when retrieving the last released version in dotnet workflow ([@matt-edmondson](https://github.com/matt-edmondson))
- Update exclusion pattern for hidden files in dotnet workflow ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.5 (patch)

Changes since v1.3.4:

- Fix license ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.4 (patch)

Changes since v1.3.3:

- Replace LICENSE file with LICENSE.md ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.1 (patch)

Changes since v1.3.0:

- Update .NET workflow to trigger on main and develop branches ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.3.0 (minor)

Changes since v1.2.0:

- Refactor AppData to use Lazy<T> for internal state ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.2.0 (minor)

Changes since 1.1.0:

- Add compatibility suppressions and update build properties ([@matt-edmondson](https://github.com/matt-edmondson))
- Add comprehensive tests for AppData methods ([@matt-edmondson](https://github.com/matt-edmondson))
- Add GitHub Actions workflow to automate issue and PR management for ktsu.dev project ([@matt-edmondson](https://github.com/matt-edmondson))
- Add new tests and update namespace in AppDataTests.cs ([@matt-edmondson](https://github.com/matt-edmondson))
- Add new tests for StrongName and Storage classes ([@matt-edmondson](https://github.com/matt-edmondson))
- dotnet-pipeline.yml renamed to dotnet-workflow.yml ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance AppData functionality and documentation ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance AppDataStorage docs and add new examples ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance AppDataTests with new tests and improvements ([@matt-edmondson](https://github.com/matt-edmondson))
- Fix a crash on first launch if you dont have the app data directory ([@matt-edmondson](https://github.com/matt-edmondson))
- Make test classes and records public; update NoWarn property ([@matt-edmondson](https://github.com/matt-edmondson))
- Migrate ktsu.io to ktsu namespace ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor AppData class for robustness and flexibility ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor tests and add null checks for deserialized data ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor TestStrongStrings for proper resource disposal ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor visibility and enhance type conversion ([@matt-edmondson](https://github.com/matt-edmondson))
- Take latest StrongPaths ([@matt-edmondson](https://github.com/matt-edmondson))
- Update dependencies ([@matt-edmondson](https://github.com/matt-edmondson))
- Update GitHub Action version in add-to-project job ([@matt-edmondson](https://github.com/matt-edmondson))
- Update MSTest.TestFramework to version 3.7.0 ([@matt-edmondson](https://github.com/matt-edmondson))
- Update project to target both .NET 8.0 and .NET 9.0 ([@matt-edmondson](https://github.com/matt-edmondson))
- Update README with Static Instance Access feature ([@matt-edmondson](https://github.com/matt-edmondson))
- Update VERSION ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.1.45 (patch)

Changes since v1.1.44:

- Add new tests and update namespace in AppDataTests.cs ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance AppData functionality and documentation ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance AppDataStorage docs and add new examples ([@matt-edmondson](https://github.com/matt-edmondson))
- Update README with Static Instance Access feature ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.1.43 (patch)

Changes since v1.1.42:

- Add GitHub Actions workflow to automate issue and PR management for ktsu.dev project ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.1.40 (patch)

Changes since v1.1.39:

- Update dependencies ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.1.34 (patch)

Changes since v1.1.33:

- Make test classes and records public; update NoWarn property ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor visibility and enhance type conversion ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.1.3 (minor)

Changes since v1.0.0:

- Add reading and writing to arbitrary files within the app directory ([@matt-edmondson](https://github.com/matt-edmondson))
- Fix a crash on first launch if you dont have the app data directory ([@matt-edmondson](https://github.com/matt-edmondson))
- Migrate ktsu.io to ktsu namespace ([@matt-edmondson](https://github.com/matt-edmondson))
- Take latest StrongPaths ([@matt-edmondson](https://github.com/matt-edmondson))
- Update VERSION ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.0.0 (major)

Changes since 0.0.0.0:

- Add github package support ([@matt-edmondson](https://github.com/matt-edmondson))
- Add stringify convertor and update strong strings ([@matt-edmondson](https://github.com/matt-edmondson))
- Add tests ([@matt-edmondson](https://github.com/matt-edmondson))
- Added readme content ([@matt-edmondson](https://github.com/matt-edmondson))
- Alpha 1 ([@matt-edmondson](https://github.com/matt-edmondson))
- Assign dependabot PRs to matt ([@matt-edmondson](https://github.com/matt-edmondson))
- Avoid double upload of symbols package ([@matt-edmondson](https://github.com/matt-edmondson))
- Bump to version 1.0.0-alpha.10 ([@matt-edmondson](https://github.com/matt-edmondson))
- Bump version to 1.0.0-alpha.2 and add a package description ([@matt-edmondson](https://github.com/matt-edmondson))
- Bump version to 1.0.0-alpha.9 ([@matt-edmondson](https://github.com/matt-edmondson))
- Create dependabot-merge.yml ([@matt-edmondson](https://github.com/matt-edmondson))
- Create VERSION ([@matt-edmondson](https://github.com/matt-edmondson))
- Disable SourceLink in project settings ([@matt-edmondson](https://github.com/matt-edmondson))
- Dont try to push packages when building pull requests ([@matt-edmondson](https://github.com/matt-edmondson))
- dotnet 8 ([@matt-edmondson](https://github.com/matt-edmondson))
- Enable dependabot and sourcelink ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhanced testing with mock file systems ([@matt-edmondson](https://github.com/matt-edmondson))
- Ensure appdata path exists before tests run ([@matt-edmondson](https://github.com/matt-edmondson))
- Fix a bug where the serializer would never serialize anything, because it was missing the derived typeinfo ([@matt-edmondson](https://github.com/matt-edmondson))
- Fix an issue where the application domain was being truncated if it was inside a namespace. Add a package description. Attempt to include source and symbols in the nuget to help with debugging. ([@matt-edmondson](https://github.com/matt-edmondson))
- Initial commit - non working ([@matt-edmondson](https://github.com/matt-edmondson))
- Migrate from .project.props to Directory.Build.props ([@matt-edmondson](https://github.com/matt-edmondson))
- Read from AUTHORS file during build ([@matt-edmondson](https://github.com/matt-edmondson))
- Read from VERSION when building ([@matt-edmondson](https://github.com/matt-edmondson))
- Read PackageDescription from DESCRIPTION file ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor AppData<T> deserialization ([@matt-edmondson](https://github.com/matt-edmondson))
- Take latest StringifyJsonConvertorFactory ([@matt-edmondson](https://github.com/matt-edmondson))
- Take latest StrongPaths ([@matt-edmondson](https://github.com/matt-edmondson))
- Take latest StrongPaths to get a bugfix ([@matt-edmondson](https://github.com/matt-edmondson))
- Update build config ([@matt-edmondson](https://github.com/matt-edmondson))
- Update Directory.Build.props ([@matt-edmondson](https://github.com/matt-edmondson))
- Update Directory.Build.targets ([@matt-edmondson](https://github.com/matt-edmondson))
- Update docs and stabilize library version ([@matt-edmondson](https://github.com/matt-edmondson))
- Update dotnet.yml ([@matt-edmondson](https://github.com/matt-edmondson))
- Update JSON conversion strategy in AppData ([@matt-edmondson](https://github.com/matt-edmondson))
- Update LICENSE ([@matt-edmondson](https://github.com/matt-edmondson))
- Update nuget.config ([@matt-edmondson](https://github.com/matt-edmondson))
- Update ToStringJsonConverter to 1.0.0 ([@matt-edmondson](https://github.com/matt-edmondson))