RxBlazorV2 1.0.3

RxBlazorV2

A reactive programming framework for Blazor applications built on top of R3 (Reactive Extensions). RxBlazorV2 uses Roslyn source generators to automatically create observable models with reactive property bindings, command patterns, and dependency injection support.

Live Demo

Features

• Reactive State Management: Automatic change notifications using R3 observables
• Source Generation: Zero runtime reflection - all code generated at compile time
• Command Pattern: Declarative observable commands with automatic CanExecute support
• Return Commands: Commands that return values (sync and async)
• Model References: Automatic cross-model reactive subscriptions via partial constructors
• DI Integration: Automatic service registration with configurable lifetimes
• Observable Collections: Built-in support for reactive collections with batch updates
• Generic Models: Full support for generic observable models with type constraints
• Component Generation: Automatic Blazor component generation with [ObservableComponent]
• Trigger System: Multiple trigger types for different reactive scenarios
• Notification Batching: Suspend/resume change notifications for bulk updates

Installation

dotnet add package RxBlazorV2

The package includes the source generator and code fixes automatically.

Companion Packages

Quick Start

[ObservableModelScope(ModelScope.Scoped)]
[ObservableComponent]
public partial class CounterModel : ObservableModel
{
    public partial int Count { get; set; }

    [ObservableCommand(nameof(Increment))]
    public partial IObservableCommand IncrementCommand { get; }

    private void Increment() => Count++;
}

@page "/counter"
@inherits CounterModelComponent

<p>Count: @Model.Count</p>
<button @onclick="() => Model.IncrementCommand.Execute()">Increment</button>

Core Concepts

Observable Properties

Properties marked as partial with both getter and setter are automatically enhanced with change notifications, value equality checks, and integration with the reactive observable stream.

public partial class MyModel : ObservableModel
{
    public partial string Name { get; set; } = "Default";
    public partial int Count { get; set; }
}

Observable Commands

Commands link UI actions to model methods with automatic CanExecute tracking.

[ObservableCommand(nameof(Save), nameof(CanSave))]
public partial IObservableCommandAsync SaveCommand { get; }

[ObservableCommand(nameof(Calculate))]
public partial IObservableCommandR<int> CalculateCommand { get; }

private async Task Save() { /* ... */ }
private bool CanSave() => !string.IsNullOrEmpty(Name);
private int Calculate() => Count * 2;

Model References (Partial Constructor Pattern)

Models can reference and react to changes in other models through the partial constructor pattern:

[ObservableModelScope(ModelScope.Scoped)]
public partial class ShoppingCartModel : ObservableModel
{
    // Declare dependencies via partial constructor
    public partial ShoppingCartModel(ProductCatalogModel catalog, ILogger logger);

    // Generator creates:
    // - protected ProductCatalogModel Catalog { get; } with auto-subscription
    // - private readonly ILogger _logger field

    public partial decimal Total { get; set; }

    private void RecalculateTotal()
    {
        Total = Quantity * Catalog.Price; // Access referenced model
    }
}

Key Points:

• ObservableModel parameters become protected properties with auto-subscription
• Other service parameters become private readonly fields with underscore prefix
• Observable streams are automatically merged from referenced models

Component Generation

Use [ObservableComponent] to generate a Blazor component base class:

[ObservableModelScope(ModelScope.Scoped)]
[ObservableComponent] // Generates MyModelComponent
public partial class MyModel : ObservableModel
{
    public partial string Title { get; set; }
}

@page "/mypage"
@inherits MyModelComponent

<h1>@Model.Title</h1>

Options:

• componentName: Custom component class name (default: {ModelName}Component)
• includeReferencedTriggers: Include triggers from referenced models (default: true)

Trigger System

RxBlazorV2 provides multiple trigger types for different reactive scenarios:

Component Triggers

Generate hook methods in components for property changes:

[ObservableComponent]
public partial class SettingsModel : ObservableModel
{
    // Generates OnThemeChanged() hook in component
    [ObservableComponentTrigger]
    public partial string Theme { get; set; }

    // Async hook with custom name
    [ObservableComponentTriggerAsync(hookMethodName: "HandleDarkModeToggle")]
    public partial bool IsDarkMode { get; set; }

    // Render only - no hook generated
    [ObservableComponentTrigger(ComponentTriggerType.RenderOnly)]
    public partial int Counter { get; set; }

    // Hook only - no re-render
    [ObservableComponentTrigger(ComponentTriggerType.HookOnly)]
    public partial string BackgroundTask { get; set; }
}

ComponentTriggerType Options:

• RenderAndHook (default): Calls hook AND re-renders component
• RenderOnly: Re-renders but no hook method
• HookOnly: Calls hook but no automatic re-render

Property Triggers

Execute internal methods automatically when properties change:

public partial class ValidationModel : ObservableModel
{
    [ObservableTrigger(nameof(ValidateEmail))]
    public partial string Email { get; set; }

    [ObservableTriggerAsync(nameof(SaveAsync), nameof(CanSave))]
    public partial string Data { get; set; }

    private void ValidateEmail() { /* validation */ }
    private async Task SaveAsync() { /* save */ }
    private bool CanSave() => !string.IsNullOrEmpty(Data);
}

Callback Triggers

Allow external services to subscribe to property changes:

public partial class AuthModel : ObservableModel
{
    [ObservableCallbackTrigger]
    public partial ClaimsPrincipal? CurrentUser { get; set; }
}

// In external service:
public class AuthService
{
    public AuthService(AuthModel authModel)
    {
        authModel.OnCurrentUserChanged(() =>
        {
            // React to user changes
        });
    }
}

Command Triggers

Auto-execute commands when properties change:

public partial class SearchModel : ObservableModel
{
    public partial string Query { get; set; }

    [ObservableCommand(nameof(Search))]
    [ObservableCommandTrigger(nameof(Query))]
    public partial IObservableCommandAsync SearchCommand { get; }

    private async Task Search() { /* search logic */ }
}

Notification Batching

Group property changes for single notifications:

public partial class FormModel : ObservableModel
{
    [ObservableBatch("userInfo")]
    public partial string FirstName { get; set; }

    [ObservableBatch("userInfo")]
    public partial string LastName { get; set; }

    public void UpdateUser(string first, string last)
    {
        using (SuspendNotifications("userInfo"))
        {
            FirstName = first;
            LastName = last;
        } // Single notification fired here
    }
}

Key Attributes

Architecture

Key Design Principles:

• Model Level: Immediate, synchronous notifications for data integrity
• Consumer Level: Batched, chunked updates for UI performance
• No Runtime Reflection: All code generated at compile time
• Type Safety: Full IntelliSense and compile-time checking

Requirements

• .NET 10.0 or later
• C# 14 (for partial constructors and field keyword)
• R3 v1.3.0 or later

Sample Application

See the RxBlazorV2Sample project for comprehensive, interactive examples:

Run the sample application:

dotnet run --project RxBlazorV2Sample

Project Structure

• RxBlazorV2 - Core runtime library with base classes and interfaces
• RxBlazorV2Generator - Roslyn source generator for code generation
• RxBlazorV2CodeFix - Code analyzers and fixes for common issues
• RxBlazorV2.MudBlazor - MudBlazor button components with command binding
• RxBlazorV2Sample - Sample Blazor WebAssembly application

Diagnostics

The generator provides comprehensive diagnostics (RXBG001-RXBG072) with code fixes. See the Diagnostics Help folder for detailed documentation.

Contributing

Contributions are welcome! Please ensure:

• All tests pass
• Code follows existing patterns
• Source generator changes include corresponding tests

License

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

Credits

Built with:

• R3 - High-performance Reactive Extensions
• ObservableCollections - Reactive collection implementations
• Microsoft.CodeAnalysis - Roslyn compiler platform