Isaac.FileStorage 2.0.1

There is a newer version of this package available.
See the version list below for details.

dotnet add package Isaac.FileStorage --version 2.0.1

NuGet\Install-Package Isaac.FileStorage -Version 2.0.1

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="Isaac.FileStorage" Version="2.0.1" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Isaac.FileStorage" Version="2.0.1" />
                    

                            Directory.Packages.props

<PackageReference Include="Isaac.FileStorage" />
                    

                            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 Isaac.FileStorage --version 2.0.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Isaac.FileStorage, 2.0.1"

#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 Isaac.FileStorage@2.0.1

#: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=Isaac.FileStorage&version=2.0.1
                    

                            Install as a Cake Addin

#tool nuget:?package=Isaac.FileStorage&version=2.0.1
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

JSONStorage

A tiny, dependency-light key/value file storage library for .NET. Give it a key and any object, and it serializes the object to BSON (binary JSON) and writes it to a .j2k file named after the key: no schema, no database, no manual (de)serialization code.

Targets net10.0.

Install

dotnet add package Isaac.FileStorage

using Isaac.FileStorage;

Quick start

var store = new FileStorageEngine("data"); // creates "data" if it doesn't exist

store.Insert("user-42", new { Name = "Ada", Role = "Admin" });

var user = store.Get<dynamic>("user-42");

foreach (var key in store.GetAllKeys())
    Console.WriteLine(key);

store.Delete("user-42");

Each entry is stored as its own <key>.j2k file inside the storage directory. Keys map directly to file names, so anything that's a valid file name works as a key.

API

Member	Description
`FileStorageEngine(string dirPath)`	Opens (or creates) the storage directory at `dirPath`. `DirectoryPath` exposes the resolved full path.
`void Insert<T>(string key, T obj)`	Serialises `obj` to BSON and writes/overwrites `<key>.j2k`. Inserting under an existing key replaces its contents.
`T Get<T>(string key)`	Reads `<key>.j2k` and deserialises it into `T`.
`IEnumerable<string> GetAllKeys()`	Returns every key currently stored (i.e. every `.j2k` file's base name) in the storage directory.
`void Delete(string key)`	Deletes `<key>.j2k`.

Exceptions

All custom exceptions live in Isaac.FileStorage.CustomExceptions.

Exception	Thrown by	When
`EmptyKeyException`	`Insert`, `Get`, `Delete`	`key` is `null` or empty.
`InvalidKeyException`	`Insert`, `Get`, `Delete`	`key` would resolve to a path outside the storage directory (e.g. contains `..` traversal or is an absolute path).
`StorageKeyNotFoundException`	`Delete`	`key` doesn't exist.
`InvalidOperationException`	`Insert`, `Get`, `Delete`	An unexpected I/O or (de)serialisation failure occurred (e.g. corrupt file, type mismatch, file locked by another process). The original exception is preserved as `InnerException`.

FileStorageEngine's constructor also throws ArgumentNullException/ArgumentException if dirPath is null or empty.

Notes

Storage format is BSON, written to .j2k files.
As of 2.0, keys are validated so they can never resolve to a path outside the storage directory.
2.0 dropped automatic migration of legacy pre-0.3 plain-JSON .jk files — if you're upgrading from one of those very old versions, convert your data before updating past 1.6.

Product	Compatible and additional computed target framework versions.
.NET	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.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- Newtonsoft.Json (>= 13.0.3)
- Newtonsoft.Json.Bson (>= 1.0.3)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
2.2.1	121	7/23/2026
2.2.0	117	7/23/2026
2.0.1	109	7/22/2026
1.6.0	713	3/8/2022
1.5.0	585	3/8/2022
1.3.0	543	2/16/2021
1.1.0	595	3/8/2022
1.0.0	561	1/24/2021
0.3.4	580	1/15/2021
0.3.3	551	1/15/2021
0.3.2	647	1/10/2021
0.3.1	837	1/9/2021
0.2.5	1,076	1/6/2021
0.2.4	1,072	1/6/2021
0.2.3	719	1/6/2021
0.2.2	729	1/6/2021
0.2.1	960	1/6/2021
0.2.0	1,458	1/5/2021

2.0.0 is a breaking release: custom exceptions moved to Isaac.FileStorage.CustomExceptions, and KeyNotFoundException was renamed to StorageKeyNotFoundException to avoid colliding with System.Collections.Generic.KeyNotFoundException. Automatic migration of legacy pre-0.3 .jk files is no longer performed. A path-traversal vulnerability in key handling was fixed (keys can no longer escape the storage directory; invalid keys throw InvalidKeyException). Insert, Get, and Delete now consistently wrap unexpected failures in InvalidOperationException with the original exception preserved as InnerException. Retargeted to net10.0.