DocumentStores 0.1.4

.NET Standard 2.0
dotnet add package DocumentStores --version 0.1.4
NuGet\Install-Package DocumentStores -Version 0.1.4
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="DocumentStores" Version="0.1.4" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DocumentStores --version 0.1.4
#r "nuget: DocumentStores, 0.1.4"
#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 DocumentStores as a Cake Addin
#addin nuget:?package=DocumentStores&version=0.1.4

// Install DocumentStores as a Cake Tool
#tool nuget:?package=DocumentStores&version=0.1.4


A file-based key-value-store, using the popular Newtonsoft.Json serialization library.
Features include exception-handling via result-types, and semaphores for thread-safety.

Adding the Package

dotnet add package DocumentStores

Using the Store

// Define your model
class Person { public string name; public int age; }

// Create new json-file-store, using default directory: $(appData)/$(appName)/
var store = new JsonFileDocumentStore();

// Put some data
await store.PutDocumentAsync("person1", new Person { name = "Jan", age = 24 });

// Read the data.
// The store does not throw Exceptions (but ArgumentExceptions). All methods return results.
var result = await store.GetDocumentAsync<Person>("person1");

// Access the data or throw exception in case of errors.
Person person = result.Validate();

You can process the result in more sophisticated ways.

Using the Try-method,

if (result.Try(out Person? person, out Exception? ex))

... or the Handle-method,

result.Handle(HandleData, HandleError);

Similar methods exist for result-tasks.

Person person = await store.GetDocumentAsync(...).ValidateAsync();
await store.GetDocumentAsync(...).HandleAsync(HandleData, HandleError);

Optimized Usage

You can define type-bound partitions within a store, so-called Topics.

var maintainerTopic = store.ToTopic<Person>("maintainers");

await maintainerTopic.PutAsync("jan", new Person { name = "Jan", age = 24 }).ValidateAsync();
await maintainerTopic.PutAsync("elisa", new Person { name = "Elisa", age = 22 }).ValidateAsync();

var maintainers = await maintainerTopic.GetAllAsync();

If you repeatedly access a single document, create a Channel, a syntactic shortcut for omitting the key.

var ownerChannel = maintainerTopic.ToChannel("jan");

Person owner = await ownerChannel.GetAsync().ValidateAsync();
owner.age += 1;
await ownerChannel.PutAsync(owner);

For caching scenarios, the .GetOrAdd() method comes in handy.

var data = await dataTopic.GetOrAddAsync("id", id => api.GetAsync(id));

The .AddOrUpdate() is useful when storing collections.

await settingsChannel.AddOrUpdateAsync(
    initialData: ImmutableList.Create("val"),
    updateData: list => list.Add("val")

Advanced Configuration

To chose a different location for the store, initialize it like so:

var store = new JsonFileDocumentStore(rootDirectory: "C:/Store");

Encryption is supported.

var store = new JsonFileDocumentStore(password: "myPassword");

More can be configured by using the options:

var options = JsonFileDocumentStoreOptions
            .WithKey(new byte[] { 1, 2, 3, 4 })
            .WithIV(new byte[] { 1, 2, 3, 4 })

var store = new JsonFileDocumentStore(options);
Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48 net481
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

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
0.1.4 796 3/1/2020
0.1.2 523 1/17/2020
0.0.11 656 11/30/2019

- Fixed bug when calling from unmanaged code.