BladeState 1.0.2

BladeState

BladeState is a lightweight server-side dependency injection state persistence library for .NET applications. It provides dependency-injected storage for persisting state across requests without relying on HttpContext.Session.

✨ Features

• 🗂 Server-side storage abstraction
• ⚡ Easy integration with Dependency Injection
• 🔄 Works across Razor & Blazor server applications
• 🔧 Extensible design for custom providers (e.g. Redis, SQL, Memory Cache)

🚀 Installation

Install via NuGet:

dotnet add package BladeState

🛠 Providers

BladeState includes multiple built-in providers for persisting state:

1. Memory Cache Provider (MemoryCacheBladeStateProvider<T>) ⚡

Stores state in in-memory cache for the lifetime of the application.

using BladeState;
using BladeState.Models;
using BladeState.Providers;

builder.Services.AddBladeState<MyState, MemoryCacheBladeStateProvider<MyState>>();

2. SQL Provider (SqlBladeStateProvider<T>) 📃

The SQL provider stores state in a relational database table using JSON serialization.

Example schema

CREATE TABLE BladeState (
    InstanceId NVARCHAR(256) PRIMARY KEY,
    [Data] NVARCHAR(MAX) NOT NULL
);

Registration

using Microsoft.Data.SqlClient;
using BladeState;
using BladeState.Models;
using BladeState.Providers;

builder.Services.AddBladeState<MyState, SqlBladeStateProvider<MyState>>(
    () => new SqlConnection("Server=localhost;Database=BladeStateDb;User Id=yourUserId;Password=YourStrong(!)Password;TrustServerCertificate=True;"))
    (
        new BladeStateProfile
        {
            InstanceName = "MyBladeStateTable"
            EncryptionKey = "my-crypto-key"
        }
    );

How it works

• Uses a simple key/value table (InstanceId, Data).
• JSON serialization handled automatically.

3. Redis Provider (RedisBladeStateProvider<T>) 🔥

Stores state in Redis using StackExchange.Redis.

Registration

using BladeState.Providers;
using StackExchange.Redis;

builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect("localhost")
);

builder.Services.AddBladeState<MyState, RedisBladeStateProvider<MyState>>(
    new BladeStateProfile
    {
        InstanceName = "MyAppUsingRedis" //If InstanceName is not provided the value will be 'BladeState'
    }
);

Notes

• Stores JSON under a Redis key formatted like {BladeStateProfile.InstanceName}-{BladeStateProfile.InstanceId}.
• Fast, distributed, great for scale-out.

4. EF Core Provider (EfCoreBladeStateProvider<T>) 🟢

Uses an Entity Framework DbContext to persist state directly in your model.

Registration

using BladeState;
using BladeState.Models;
using BladeState.Providers;
using Microsoft.EntityFrameworkCore;

builder.Services.AddDbContext<MyDbContext>(options =>
    options.UseSqlServer("Server=localhost;Database=BladeStateDb;User Id=sa;Password=YourStrong(!)Password;TrustServerCertificate=True;"));

builder.Services.AddBladeState<MyState, EfCoreBladeStateProvider<MyState>>(
    new BladeStateProfile
    {
        InstanceName = "MyEfCoreState",
        EncryptionKey = "my-crypto-key"
    }
);

Notes

• Assumes T maps directly to a table via EF Core.
• Uses normal DbContext.SaveChangesAsync() semantics.
• Best for when you want strongly typed schema vs JSON.

⚖️ Provider Comparison

🧩 Simple Service Collection Wire-up

Usage:

builder.Services.AddBladeState<MyState, SqlBladeStateProvider<MyState>>();

📖 Example: Consuming State

public class MyService
{
    private readonly BladeStateProvider<MyState> _stateProvider;

    public MyService(BladeStateProvider<MyState> stateProvider)
    {
        _stateProvider = stateProvider;
    }

    public async Task DoWorkAsync()
    {
        var state = await _stateProvider.LoadStateAsync();
        state.Counter++;
        await _stateProvider.SaveStateAsync(state);
    }
}

💿 Drive BladeState with BladeStateProfile!

var profile = new BladeStateProfile
{
    InstanceId = string.Empty,
    InstanceName = "MyApplicationState",
    InstanceTimeout = TimeSpan.FromMinutes(120),
    SaveOnInstanceTimeout = true,
    AutoEncrypt = true,
    EncryptionKey = "my-crypto-key"
}

⚙️ Example: Binding Profile from appsettings.json

You can configure profiles from appsettings.json and register them directly with a couple simple steps:

1. Add the following structure to your appsettings.json file

{
  "BladeState": {
    "Profile": {
      "InstanceId": "MyApplicationState",
      "EncryptionKey": "my-crypto-key"
    }
  }
}

2. Get the section and pass the BladeStateProfile to the 'AddBladeState();' extension method in your Program.cs

using BladeState;
using BladeState.Models;
using BladeState.Providers;

var profile = builder.Configuration.GetSection("BladeState:Profile").Get<BladeStateProfile>();

builder.Services.AddBladeState<MyAppState, SqlBladeStateProvider<MyAppState>>(profile);

❔🪽 Built-in Encryption

BladeState automatically encrypts persisted state data using AES encryption.

Enabled by default – you don’t need to do anything.

Encryption key – if not provided, BladeState will generate one automatically, simplifying encryption and decryption without explicit wire-up.
You may also supply your own key by configuring a BladeStateProfile, example below:

var profile = new BladeStateProfile
{
    AutoEncrypt = true,              // enable encryption
    EncryptionKey = "my-crypto-key"  // optional custom key
};

builder.Services.AddBladeState<MyAppState, SqlBladeStateProvider<MyAppState>>(profile);

Optionally (and NOT to be used for Production Environments - the universe frowns heavily upon that action 😔): You may turn off encryption – you can explicitly disable it via AutoEncrypt in your profile:

This is not necessary even when wiring up your own BladeStateProvider. The Decrypt/Encrypt State methods should be explicitly used.

var profile = new BladeStateProfile
{
    AutoEncrypt = false  // disables automatic crypto transforms in the 'out of the box' providers
};

builder.Services.AddBladeState<MyAppState, RedisBladeStateProvider<MyAppState>>(profile);

❗Built-In Events

When a provider method is called an event will be raised to be handled by consuming components and services. This is useful for reliable UI updates.

// inject the provider
[Inject]
required public MemoryCacheBladeStateProvider<MyState> Provider { get; set; }

// add an event handler (anonymously)
Provider.OnStateChange += (sender, args) =>
{
    // get updated state if need be
    var state = args.State;

    // do something
    Console.WriteLine($"State changed: {args.EventType} for {args.InstanceId}! There are now {state.Items.Count} items!");
};

// add a custom handler
Provider.OnStateChange += MyCustomEventHandler;

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.