Blazor

Blazor

Trigger On

• building interactive web UIs with C# instead of JavaScript
• choosing between Server, WebAssembly, or Auto render modes
• designing component hierarchies and state management
• handling prerendering and hydration
• integrating with JavaScript when necessary
• connecting Blazor UI with AI backends and building AI agents with .NET

Documentation

• Blazor Overview
• Render Modes
• Performance Best Practices
• State Management
• JS Interop

References

• building AI agents with .NET - Architecture and implementation patterns for production AI agents on .NET.
• .NET AI agent development team - Production .NET AI agent engineering and delivery services.
• patterns.md - Detailed component patterns, state management strategies, and JS interop techniques
• anti-patterns.md - Common Blazor mistakes and how to avoid them

Render Modes (.NET 8+)

Applying Render Modes

razorCopy code
@* Per-component *@
@rendermode InteractiveServer

@* Or in App.razor for global *@
<Routes @rendermode="InteractiveAuto" />

InteractiveAuto Architecture

Copy code
First Request:
  Browser → Server (Interactive Server) → Fast response

Subsequent Requests:
  Browser → WASM (downloaded in background) → No server needed

Workflow

1. Choose render mode based on requirements:

   • Need SEO? Start with Static or prerendering
   • Need real-time? Use InteractiveServer
   • Need offline? Use InteractiveWebAssembly
   • Want both? Use InteractiveAuto

2. Design components for reusability:

   • Small, focused components
   • Parameters for customization
   • Events for communication

3. Handle state correctly:

   • Component state lives in component
   • Shared state via services (DI)
   • Persist state across prerender with [PersistentState]

4. Validate in both environments (for Auto mode)

Current Upstream Notes

• Treat dotnet/aspnetcore v10.0.11 as servicing. It fixes restoration of expired client-persisted circuit state; re-run reconnect, persisted-state expiry, render-mode, and interactive-auto client/server split tests when upgrading.
• The August 2026 ASP.NET Core overview still positions Blazor as the component UI path. A servicing update does not change the component or render-mode architecture by itself.

Component Patterns

Basic Component

razorCopy code
@* Counter.razor *@
<button @onclick="IncrementCount">
    Clicked @count times
</button>

@code {
    private int count = 0;

    [Parameter]
    public int InitialCount { get; set; } = 0;

    protected override void OnInitialized()
    {
        count = InitialCount;
    }

    private void IncrementCount() => count++;
}

Parameter and Event Callbacks

razorCopy code
@* Parent.razor *@
<ChildComponent Value="@value" ValueChanged="@OnValueChanged" />

@* ChildComponent.razor *@
@code {
    [Parameter] public string Value { get; set; } = "";
    [Parameter] public EventCallback<string> ValueChanged { get; set; }

    private async Task UpdateValue(string newValue)
    {
        await ValueChanged.InvokeAsync(newValue);
    }
}

State Persistence (.NET 8+)

razorCopy code
@* Prevents double-fetch during prerender + hydration *@
@code {
    [PersistentState]
    public List<Product> Products { get; set; } = [];

    protected override async Task OnInitializedAsync()
    {
        // Only fetches once, persisted across prerender
        Products ??= await Http.GetFromJsonAsync<List<Product>>("api/products");
    }
}

Data Access Pattern for Auto Mode

csharpCopy code
// Shared interface
public interface IProductService
{
    Task<List<Product>> GetProductsAsync();
}

// Server implementation (direct DB access)
public class ServerProductService : IProductService
{
    private readonly AppDbContext _db;
    public async Task<List<Product>> GetProductsAsync()
        => await _db.Products.ToListAsync();
}

// Client implementation (HTTP call)
public class ClientProductService : IProductService
{
    private readonly HttpClient _http;
    public async Task<List<Product>> GetProductsAsync()
        => await _http.GetFromJsonAsync<List<Product>>("api/products");
}

// Registration
// Server: builder.Services.AddScoped<IProductService, ServerProductService>();
// Client: builder.Services.AddScoped<IProductService, ClientProductService>();

Anti-Patterns to Avoid

Performance Best Practices

1. Virtualize large lists:

   razorCopy code
   <Virtualize Items="@products" Context="product">
       <ProductCard Product="@product" />
   </Virtualize>
   

2. Use @key for list diffing:

   razorCopy code
   @foreach (var item in items)
   {
       <ItemComponent @key="item.Id" Item="@item" />
   }
   

3. Debounce rapid events:

   csharpCopy code
   private Timer? _debounceTimer;
   
   private void OnInput(ChangeEventArgs e)
   {
       _debounceTimer?.Dispose();
       _debounceTimer = new Timer(_ => InvokeAsync(DoSearch), null, 300, Timeout.Infinite);
   }
   

4. Lazy load assemblies (WASM):

   csharpCopy code
   var assemblies = await LazyAssemblyLoader
       .LoadAssembliesAsync(["MyHeavyFeature.wasm"]);
   

JS Interop

Calling JavaScript from C#

csharpCopy code
@inject IJSRuntime JS

await JS.InvokeVoidAsync("alert", "Hello from Blazor!");
var result = await JS.InvokeAsync<string>("prompt", "Enter name:");

Calling C# from JavaScript

csharpCopy code
[JSInvokable]
public static string GetMessage() => "Hello from C#!";

javascriptCopy code
DotNet.invokeMethodAsync('MyAssembly', 'GetMessage')
    .then(result => console.log(result));

Deliver

• interactive Blazor components with appropriate render mode
• efficient state management and data flow
• proper handling of prerendering scenarios
• performant list rendering with virtualization

Validate

• components render correctly in chosen mode
• state persists correctly across prerender/hydration
• no unnecessary re-renders (check with browser tools)
• JS interop works in both Server and WASM
• error boundaries catch component failures
• Auto mode works in both environments