BlazorFlow

A lightweight state management library for Blazor WebAssembly and Blazor Server applications implementing the Mediator pattern with CQRS support and async result tracking.

Features

• Blazor Server & WASM Support: Works seamlessly with both hosting models
• Thread-Safe Navigation: Navigate from handlers safely in both WASM and Server
• Mediator Pattern: Decouples request handling from your Blazor components
• CQRS Support: Separate command (write) and query (read) operations
• Global Handlers: Add cross-cutting concerns (logging, validation, auditing) to all commands
• Async State Tracking: Built-in loading, success, and error states
• Reactive UI Updates: Automatic component re-rendering with state changes
• Type-Safe: Full generic type support for request/response pairs
• Cancellation Support: CancellationToken support throughout
• Progress Updates: Handlers can notify UI during long-running operations
• Auto-Discovery: Automatic handler registration via reflection
• Thread-Safe Operations: Automatic UI thread marshaling for all operations

Installation

Install via NuGet Package Manager:

dotnet add package BlazorFlow --version 0.1.0-preview.1

Or via Package Manager Console:

Install-Package BlazorFlow -Version 0.1.0-preview.1

Quick Start

1. Register BlazorFlow in your Program.cs

using BlazorFlow.Extensions; using System.Reflection; var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.RootComponents.Add<App>("#app"); // Register BlazorFlow with automatic handler discovery builder.Services.AddBlazorFlowStateMediator(Assembly.GetExecutingAssembly()); await builder.Build().RunAsync();

2. Create a Command/Query

using BlazorFlow.Abstractions; // Query that returns data public record GetWeatherForecastQuery : IBlazorCommandRequest<WeatherForecast[]>; // Command that performs an action public record IncrementCounterCommand(int Amount) : IBlazorCommandRequest<int>;

3. Create a Handler

using BlazorFlow.Abstractions; public class GetWeatherForecastHandler : IBlazorCommand<GetWeatherForecastQuery, WeatherForecast[]> { public async Task<WeatherForecast[]> HandleAsync( GetWeatherForecastQuery request, ICommandContext context, CancellationToken cancellationToken = default) { // Simulate API call await Task.Delay(1000, cancellationToken); return new[] { new WeatherForecast(DateOnly.FromDateTime(DateTime.Now), 20, "Sunny") }; } }

4. Use in Your Blazor Component

@page "/weather" @using BlazorFlow.Abstractions @inject IStateMessageBus MessageBus <h3>Weather Forecast</h3> @if (weatherResult == null) { <button @onclick="LoadWeather">Load Weather</button> } else if (weatherResult.IsLoading) { <p>Loading...</p> } else if (weatherResult.IsSuccess && weatherResult.Value != null) { <ul> @foreach (var forecast in weatherResult.Value) { <li>@forecast.Date: @forecast.TemperatureC°C - @forecast.Summary</li> } </ul> } else if (weatherResult.IsError) { <div class="alert alert-danger"> Error: @weatherResult.ErrorMessage </div> } @code { private IAsyncResult<WeatherForecast[]>? weatherResult; private void LoadWeather() { weatherResult = MessageBus.Publish<GetWeatherForecastQuery, WeatherForecast[]>( new GetWeatherForecastQuery()); weatherResult.StateChanged += StateHasChanged; } }

Advanced Features

Thread-Safe Navigation

Navigate from command handlers safely in both Blazor WASM and Server:

public class LoginHandler : IBlazorCommand<LoginCommand, LoginResult> { public async Task<LoginResult> HandleAsync( LoginCommand request, ICommandContext context, CancellationToken cancellationToken = default) { // Authenticate user var user = await AuthenticateAsync(request.Username, request.Password); if (user != null) { // Thread-safe navigation - works in both WASM and Server! context.NavigateTo("/dashboard"); return new LoginResult { Success = true }; } return new LoginResult { Success = false, Error = "Invalid credentials" }; } }

Key Benefits:

• ✅ No DI required: Use context.NavigateTo() instead of injecting NavigationManager
• ✅ Thread-safe: Automatically marshaled to UI thread in Blazor Server
• ✅ Works everywhere: Same code works in both WASM and Server
• ✅ Background-safe: Call from async operations without threading issues

Real-Time Progress Updates

Handlers can notify the UI during long-running operations:

public class ProcessFilesHandler : IBlazorCommand<ProcessFilesCommand, FileProcessingResult> { public async Task<FileProcessingResult> HandleAsync( ProcessFilesCommand request, ICommandContext context, CancellationToken cancellationToken = default) { for (int i = 0; i < files.Count; i++) { await ProcessFileAsync(files[i], cancellationToken); // Notify UI to re-render with progress context.StateHasChanged(); } return new FileProcessingResult(files.Count); } }

Reactive Callbacks

Chain operations with reactive callbacks:

var result = MessageBus.Publish<AddTodoCommand, TodoItem>(new AddTodoCommand("New Task")); result.StateChanged += StateHasChanged; result.OnSuccess(todo => { Console.WriteLine($"Todo added: {todo.Title}"); LoadTodos(); // Refresh the list }); result.OnError(ex => { Console.WriteLine($"Error: {ex.Message}"); });

Pattern Matching

Use the Match method for functional-style result handling:

var message = result.Match( onSuccess: value => $"Success: {value}", onError: ex => $"Error: {ex.Message}", onLoading: () => "Loading..." );

Global Handlers (v0.3.0+)

NEW in v0.3.0: Add cross-cutting concerns like logging, validation, auditing, and error handling to all commands using global handlers.

Global handlers execute in a pipeline around your command handlers:

OnRequest → Main Handler → OnSuccess/OnError

Types of Global Handlers

1. Request Handlers - Execute before command processing
2. Success Handlers - Execute after successful command execution
3. Error Handlers - Execute when commands throw exceptions

Registration

Register global handlers in Program.cs:

using BlazorFlow.Extensions; builder.Services.AddBlazorFlowMediator(options => { // Add global request handlers (execute before command) options.AddRequestHandler<LoggingRequestHandler>(); options.AddRequestHandler<ValidationRequestHandler>(); // Add global success handlers (execute after success) options.AddSuccessHandler<AuditingSuccessHandler>(); // Add global error handlers (execute on errors) options.AddErrorHandler<ErrorNotificationHandler>(); }, Assembly.GetExecutingAssembly());

Example: Logging Handler

public class LoggingRequestHandler : IBlazorCommandRequestHandler { private readonly ILogger<LoggingRequestHandler> _logger; public LoggingRequestHandler(ILogger<LoggingRequestHandler> logger) { _logger = logger; } public Task OnRequestAsync(RequestContext context, CancellationToken cancellationToken = default) { _logger.LogInformation("Executing command: {RequestType} at {Timestamp}", context.RequestType?.Name ?? "Unknown", context.Timestamp); // Access request data if needed: // var request = context.GetRequest<YourRequestType>(); return Task.CompletedTask; } }

Example: Error Notification Handler

public class ErrorNotificationHandler : IBlazorCommandErrorHandler { private readonly ILogger<ErrorNotificationHandler> _logger; public ErrorNotificationHandler(ILogger<ErrorNotificationHandler> logger) { _logger = logger; } public Task OnErrorAsync(RequestContext context, CancellationToken cancellationToken = default) { _logger.LogError(context.Exception, "Command {CommandType} failed", context.RequestType?.Name ?? "Unknown"); // Access request data if needed: // var request = context.GetRequest<YourRequestType>(); // You could also publish error notifications to the UI here return Task.CompletedTask; } }

Key Features

• ✅ Full DI Support: All handlers resolved from dependency injection
• ✅ Simple Non-Generic Design: No complex generic type registrations needed
• ✅ RequestContext API: Access request/response data via context.GetRequest<T>() and context.GetResponse<T>()
• ✅ JSON Storage: Request/response automatically serialized and cleared after completion
• ✅ Access to Context: All handlers receive RequestContext with ICommandContext for UI operations
• ✅ Error Isolation: Failed global handlers don't break the pipeline
• ✅ Order Preservation: Handlers execute in registration order

Architecture

BlazorFlow implements the Mediator pattern with CQRS principles:

Blazor Component ↓ (Publishes request) IStateMessageBus ↓ (Routes to handler) IBlazorCommand Handler ↓ (Executes logic) IAsyncResult<T> ↓ (Tracks state: Loading → Success/Error) Blazor Component (Re-renders via StateChanged event)

Documentation

For more examples and detailed documentation, see the samples directory.

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Roadmap

• Multi-targeting support (net8.0, net9.0)
• Blazor Server support (v0.2.0+)
• Pipeline behaviors / Global handlers (v0.3.0+)
• Request/response interceptors via global handlers (v0.3.0+)
• Handler result caching
• Performance optimizations

---

Note: This is a preview release. APIs may change in future versions.