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.
dotnet add package DocumentStores
// 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))
HandleData(person!)
else
HandleError(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);
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")
);
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
.Default
.WithRootDirectory("C:/Temp")
.WithEncryptionOptions(
EncryptionOptions.Aes
.WithKey(new byte[] { 1, 2, 3, 4 })
.WithIV(new byte[] { 1, 2, 3, 4 })
)
);
var store = new JsonFileDocumentStore(options);