Hexalith.KeyValueStorages.DaprComponents 2.1.2

Hexalith.KeyValueStorages.DaprComponents

This library provides a Dapr actor-based implementation of the key-value storage interface. It uses Dapr actors to ensure concurrency control and data consistency.

Features

• Thread-safe key-value storage using Dapr actors
• Automatic concurrency control with etags
• Serialization support for keys and values
• Easy integration with ASP.NET Core and Dapr applications

Getting Started

Prerequisites

• .NET 9.0 or later
• Dapr runtime installed and configured

Installation

Add the package to your project:

dotnet add package Hexalith.KeyValueStorages.DaprComponents

Usage

1. Register the actor and key-value storage in your ASP.NET Core application

using Hexalith.KeyValueStorages;
using Hexalith.KeyValueStorages.DaprComponents.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register the Dapr actor key-value storage
builder.Services.AddDaprActorKeyValueStorage<string, MyData, KeyToStringSerializer<string>, MyDataSerializer>();

var app = builder.Build();

// Configure the Dapr actors middleware
app.UseRouting();
app.UseEndpoints(endpoints =>
{
 endpoints.MapActorsHandlers();
});

app.Run();

2. Create a value serializer

using System.Text.Json;
using Hexalith.KeyValueStorages;

public class MyDataSerializer : IValueSerializer<MyData, string>
{
 public string DataType => "application/json";

 public (MyData Value, string Etag) Deserialize(string value)
 {
 var document = JsonDocument.Parse(value);
 var root = document.RootElement;
 
 string etag = root.GetProperty("etag").GetString() ?? throw new InvalidOperationException("Etag is missing");
 MyData data = JsonSerializer.Deserialize<MyData>(root.GetProperty("data").GetRawText()) 
 ?? throw new InvalidOperationException("Failed to deserialize data");
 
 return (data, etag);
 }

 public async Task<(MyData Value, string Etag)> DeserializeAsync(Stream stream, CancellationToken cancellationToken)
 {
 using var document = await JsonDocument.ParseAsync(stream, cancellationToken: cancellationToken);
 var root = document.RootElement;
 
 string etag = root.GetProperty("etag").GetString() ?? throw new InvalidOperationException("Etag is missing");
 MyData data = JsonSerializer.Deserialize<MyData>(root.GetProperty("data").GetRawText()) 
 ?? throw new InvalidOperationException("Failed to deserialize data");
 
 return (data, etag);
 }

 public string Serialize(MyData value, string etag)
 {
 var wrapper = new { data = value, etag };
 return JsonSerializer.Serialize(wrapper);
 }

 public async Task SerializeAsync(Stream stream, MyData value, string etag, CancellationToken cancellationToken)
 {
 var wrapper = new { data = value, etag };
 await JsonSerializer.SerializeAsync(stream, wrapper, cancellationToken: cancellationToken);
 }
}

3. Use the key-value storage in your application

public class MyService
{
 private readonly IKeyValueStore<string, MyData, string> _storage;

 public MyService(IKeyValueStore<string, MyData, string> storage)
 {
 _storage = storage;
 }

 public async Task SaveDataAsync(string key, MyData data, CancellationToken cancellationToken)
 {
 // Add new data
 string etag = await _storage.AddAsync(key, data, cancellationToken);
 
 // Update existing data
 data.UpdatedAt = DateTime.UtcNow;
 string newEtag = await _storage.SetAsync(key, data, etag, cancellationToken);
 
 // Get data
 StoreResult<MyData, string> result = await _storage.GetAsync(key, cancellationToken);
 Console.WriteLine($"Data: {result.Value}, Etag: {result.Etag}");
 }
}

How It Works

The Dapr actor-based key-value storage uses Dapr actors to ensure that only one operation can be performed on a key at a time. This prevents race conditions and ensures data consistency.

1. Each key-value pair is stored in the actor's state
2. The actor handles concurrency control using etags
3. The actor ensures that only one operation can be performed on a key at a time

Configuration

You can configure the actor settings when registering the key-value storage:

builder.Services.AddDaprActorKeyValueStorage<string, MyData, KeyToStringSerializer<string>, MyDataSerializer>(
 actorTypeName: "CustomKeyValueStoreActor");

Advanced Usage

Custom Actor Type Name

You can specify a custom actor type name when registering the key-value storage:

builder.Services.AddDaprActorKeyValueStorage<string, MyData, KeyToStringSerializer<string>, MyDataSerializer>(
 actorTypeName: "CustomKeyValueStoreActor");

Custom Key Serializer

You can create a custom key serializer by implementing the IKeySerializer<TKey> interface:

public class CustomKeySerializer<TKey> : IKeySerializer<TKey>
 where TKey : notnull
{
 public string Serialize(TKey key)
 {
 // Custom serialization logic
 return key.ToString() ?? throw new InvalidOperationException("Key cannot be null");
 }
}

Custom Value Serializer

You can create a custom value serializer by implementing the IValueSerializer<TValue, TEtag> interface:

public class CustomValueSerializer<TValue> : IValueSerializer<TValue, string>
{
 public string DataType => "application/custom";

 public (TValue Value, string Etag) Deserialize(string value)
 {
 // Custom deserialization logic
 // ...
 }

 public Task<(TValue Value, string Etag)> DeserializeAsync(Stream stream, CancellationToken cancellationToken)
 {
 // Custom async deserialization logic
 // ...
 }

 public string Serialize(TValue value, string etag)
 {
 // Custom serialization logic
 // ...
 }

 public Task SerializeAsync(Stream stream, TValue value, string etag, CancellationToken cancellationToken)
 {
 // Custom async serialization logic
 // ...
 }
}