RForge.Blazor.Events 1.0.0

RForge.Blazor.Events

Typed events and reactive state for Blazor components, wherever they sit in the tree.

Status: new in RForge.Blazor 1.0.0. Tested with 96 unit/generator tests on each of net8, net9 and net10, plus a browser-driven pass over every sample page. See the design specification.

Blazor makes parent ↔ child communication easy. Communicating across the tree usually means a hand-written service with C# events, plus subscribing, unsubscribing, InvokeAsync, StateHasChanged and error handling in every component that uses it.

RForge.Blazor.Events handles that for you. It's inspired by Svelte's stores and context and adapted to Blazor's DI and rendering model.

Features

• Events: typed, fire-and-forget messages (IEvent) that any component or service can publish and handle.
• State: store-like values (IState<T>) with a current value, change notification, and no-op suppression through record equality.
• Automatic lifecycle: derive from RfEventComponent and subscriptions, re-renders, thread marshaling, ErrorBoundary integration and disposal are handled for you.
• Selectors: re-render only when the part of the state you use changes.
• Scopes: <EventScope> and <StateScope> isolate events and give subtrees their own state instances. Routes include Bubble (default), Local, Broadcast, Root, Global and Named.
• Source generator: [Subscribe] and [UseState] attributes, with no reflection, so it's trim/AOT safe. Analyzers (RFEVT001–RFEVT014) catch mistakes at build time.
• Every render mode: static SSR, Interactive Server, WebAssembly and Auto, with or without prerendering, plus opt-in state persistence from prerender to interactive.
• Works with plain components too: opt-in cascading values let third-party components read state through [CascadingParameter].

Install

dotnet add package RForge.Blazor.Events

One package contains the runtime, the source generator and the analyzers. Add it to every project that contains event-aware components (in a Blazor Web App, both the server and the .Client project), because NuGet doesn't pass analyzers through project references. See Setup for the full walkthrough.

A quick look

Register (in every Program.cs that hosts interactive components, including the .Client project for WebAssembly/Auto):

builder.Services.AddRForgeEvents();

Define events and state:

public sealed record ItemAdded(int ProductId, int Quantity) : IEvent;

public sealed record CartState(int Count, decimal Total) : IState<CartState>
{
    public static CartState Initial => new(0, 0m);
}

Publish and write state from any component:

@* ProductCard.razor *@
@inherits RfEventComponent
<button @onclick="AddToCart">Add</button>

// ProductCard.razor.cs
public partial class ProductCard
{
    [Parameter] public Product Product { get; set; } = default!;

    private async Task AddToCart()
    {
        State<CartState>().Update(s => s with { Count = s.Count + 1, Total = s.Total + Product.Price });
        await PublishAsync(new ItemAdded(Product.Id, 1));
    }
}

React anywhere else in the tree, with no shared parent needed:

@* CartBadge.razor *@
@inherits RfEventComponent
<span class="badge @(_pulse ? "pulse" : "")">@Count</span>

// CartBadge.razor.cs
public partial class CartBadge
{
    [UseState(Select = nameof(SelectCount))]
    private partial int Count { get; }                // re-renders only when Count changes
    private static int SelectCount(CartState s) => s.Count;

    [Subscribe]
    private void OnItemAdded(ItemAdded e) => _pulse = true;

    private bool _pulse;
}

Scope a subtree so each instance gets its own state and its own event channel:

<EventScope Name="checkout">
    <StateScope TState="CheckoutForm">
        <AddressForm />
        <PaymentForm />
    </StateScope>
    <OrderSummary />
</EventScope>

Render-mode support

Details: docs/events/design/render-modes.md.

Requirements

• .NET 8, 9 or 10. [Subscribe], state, scopes and the analyzers work with the .NET 8 SDK and newer.
• [UseState] needs C# 13, because it is declared as a partial property. net9 and net10 projects already compile at C# 13 or later. A net8 project defaults to C# 12, so it needs the .NET 9 SDK or newer and <LangVersion>13</LangVersion> (or latest).
• Async lambdas at C# 12. In a net8 project at the default C# 12, builder.On<MyEvent>(async e => ...) is ambiguous between the Task and ValueTask overloads (CS0121). Pass a method group, cast the lambda to Func<MyEvent, Task>, or set LangVersion to 13 or later, which resolves it.
• Members annotated with [Subscribe] / [UseState] must be in a code-behind (.razor.cs) partial class, not in a @code block. Source generators can't see the Razor compiler's output, and RFEVT001 reports it if you forget (ADR-004).
• Event-aware .razor files start with @inherits RfEventComponent. Razor otherwise declares : ComponentBase, which conflicts with a base class declared in the code-behind (ADR-017).

Samples

samples/ contains a Blazor Web App (Server + WebAssembly + Auto) with seven example pages:

dotnet run --project samples/RForge.Blazor.Events.Sample

Building and testing

dotnet build src/RForge/RForge.sln
dotnet test  src/RForge/RForge.sln

For contributors: the samples and tests in this repository reference the source projects instead of the package. A project reference to the runtime doesn't bring the generator along, so they reference both:

<ProjectReference Include="path/to/src/RForge.Blazor.Events/RForge.Blazor.Events.csproj" />
<ProjectReference Include="path/to/src/RForge.Blazor.Events.Generators/RForge.Blazor.Events.Generators.csproj"
                  OutputItemType="Analyzer" ReferenceOutputAssembly="false" />

Tutorials

Step-by-step guides with complete, compile-checked code and the recommended file layout: docs/events/tutorials.

Design documentation