Blazor Rendering Modes in .NET 8/9: Static, Server, WebAssembly & Auto

Blazor in .NET 8 and .NET 9 introduces a powerful new feature: multiple rendering modes that let you choose how your components render and interact with users. Whether you're building a content-heavy blog, a real-time dashboard, or a progressive web app, understanding these modes is crucial for performance, scalability, and user experience. In this tutorial, we'll dive deep into each mode – Static SSR, Interactive Server, Interactive WebAssembly, and Interactive Auto – with practical code examples, real-world scenarios, and debugging strategies. You'll learn not just how to use them, but when to use each one to avoid common pitfalls like slow load times, high server costs, or broken interactivity. By the end, you'll be able to architect Blazor applications that are fast, responsive, and maintainable.

Understanding Blazor Rendering Modes

Blazor in .NET 8/9 introduces four rendering modes that determine how components are rendered and how they handle interactivity. The mode is set at the component level using the @rendermode directive or globally in the App.razor file. The modes are:

• Static Server-Side Rendering (SSR): The component renders HTML on the server and sends it to the client. No interactivity; any user interaction requires a full page reload. Ideal for content-heavy pages like blogs or documentation.

• Interactive Server: The component renders on the server and maintains a real-time SignalR connection for UI updates. Interactivity is handled server-side, which means low client resources but higher server load. Best for real-time apps like dashboards.

• Interactive WebAssembly: The component runs entirely in the browser using WebAssembly. All code executes on the client, reducing server load but increasing download size. Great for offline-capable apps.

• Interactive Auto: A hybrid mode that starts with Interactive Server for the first visit (fast initial load) and then downloads the WebAssembly assets in the background. On subsequent visits, it switches to Interactive WebAssembly for faster interactions. Best for apps that need a balance between initial load time and interactivity.

You can set the render mode on a per-component basis using the @rendermode directive. For example: @rendermode InteractiveServer. You can also define custom render modes using the RenderMode class.

@page "/counter"
@rendermode InteractiveServer

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Static SSR: Fast Content Delivery

Static SSR is the simplest mode: it renders HTML on the server and sends it to the client without any interactivity. This mode is perfect for pages that don't require user input, such as blog posts, product listings, or documentation. Since there's no SignalR connection or WebAssembly download, the page loads extremely fast and uses minimal server resources.

To use Static SSR, simply omit the @rendermode directive or set it to @rendermode Static (though Static is the default for pages without an interactive mode). You can also explicitly set it:

@rendermode RenderMode.Static

Static SSR components can still contain interactive child components if those children have their own render mode. However, the static parent will not be interactive. This is useful for layouts where you want a static shell with interactive islands.

One important consideration: Static SSR components cannot use @onclick or other event handlers directly. If you need interactivity, you must either switch to an interactive mode or use JavaScript interop.

@page "/about"
@rendermode RenderMode.Static

<PageTitle>About Us</PageTitle>

<h1>About Our Company</h1>

<p>We are a leading provider of Blazor solutions. Our team has years of experience in building high-performance web applications.</p>

<p>Contact us at info@example.com</p>

Interactive Server: Real-Time UI Updates

Interactive Server mode renders components on the server and maintains a persistent SignalR connection between client and server. All UI events (button clicks, form submissions) are sent to the server via SignalR, processed, and the updated UI is sent back. This mode is ideal for applications that require real-time updates, such as dashboards, chat apps, or collaborative tools.

To enable Interactive Server, use @rendermode InteractiveServer. You can also set it globally in App.razor:

<Routes @rendermode="InteractiveServer" />

One key advantage is that all .NET code runs on the server, so you have access to server resources like databases without exposing secrets to the client. However, the downside is that each client consumes server memory and CPU, and latency can be an issue for users far from the server.

Interactive Server components can use @onclick, @bind, and other event handlers. They also support Blazor's built-in forms and validation.

@page "/realtime"
@rendermode InteractiveServer
@using Microsoft.AspNetCore.SignalR
@inject IHubContext<ChatHub> HubContext

<h1>Real-Time Chat</h1>

<div>
    <input @bind="message" placeholder="Type a message" />
    <button @onclick="SendMessage">Send</button>
</div>

<ul>
    @foreach (var msg in messages)
    {
        <li>@msg</li>
    }
</ul>

@code {
    private string message;
    private List<string> messages = new();

    private async Task SendMessage()
    {
        messages.Add(message);
        await HubContext.Clients.All.SendAsync("ReceiveMessage", message);
        message = string.Empty;
    }
}

Interactive WebAssembly: Client-Side Execution

Interactive WebAssembly mode runs Blazor components entirely in the browser using WebAssembly. The .NET code is compiled into WebAssembly and downloaded to the client, where it executes. This mode eliminates the need for a persistent server connection, reducing server load and enabling offline scenarios.

To use Interactive WebAssembly, set @rendermode InteractiveWebAssembly. Note that the initial download includes the .NET runtime and assemblies, which can be large (several MB). However, subsequent visits can be faster if the assets are cached.

Interactive WebAssembly components can access browser APIs via JavaScript interop and can use local storage, geolocation, etc. They cannot directly access server resources like databases; instead, they must call web APIs.

One important consideration: Interactive WebAssembly runs on the client, so sensitive logic (e.g., authentication) should not be exposed. Always validate on the server.

@page "/wasm"
@rendermode InteractiveWebAssembly
@inject IJSRuntime JS

<h1>Client-Side Calculator</h1>

<input @bind="number1" type="number" />
<select @bind="operation">
    <option value="+">+</option>
    <option value="-">-</option>
    <option value="*">*</option>
    <option value="/">/</option>
</select>
<input @bind="number2" type="number" />
<button @onclick="Calculate">=</button>

<p>Result: @result</p>

@code {
    private double number1, number2, result;
    private string operation = "+";

    private void Calculate()
    {
        result = operation switch
        {
            "+" => number1 + number2,
            "-" => number1 - number2,
            "*" => number1 * number2,
            "/" => number2 != 0 ? number1 / number2 : double.NaN,
            _ => 0
        };
    }
}

Interactive Auto: The Best of Both Worlds

Interactive Auto mode is a hybrid that combines Interactive Server and Interactive WebAssembly. On the first visit, the component renders using Interactive Server mode, providing fast initial load and interactivity. Meanwhile, the WebAssembly assets are downloaded in the background. On subsequent visits, the component switches to Interactive WebAssembly mode, eliminating the server round-trip for faster interactions.

To use Interactive Auto, set @rendermode InteractiveAuto. You can also configure the render mode globally:

<Routes @rendermode="InteractiveAuto" />

This mode is ideal for applications that need a fast first load but also want to reduce server load over time. However, there are caveats:

• State is not automatically preserved when switching from Server to WebAssembly. You must implement state persistence (e.g., using local storage or a state container).
• The initial Server mode still requires a SignalR connection, so server resources are used on the first visit.
• The switch to WebAssembly happens on subsequent navigations, not on the same page. So if a user stays on the same page, it remains in Server mode.

To detect the current rendering mode at runtime, use the RendererInfo service:

@inject IHostEnvironment HostEnvironment @inject RendererInfo RendererInfo

<p>Current render mode: @RendererInfo.RenderMode</p>

@page "/auto"
@rendermode InteractiveAuto
@inject RendererInfo RendererInfo

<h1>Auto Mode Demo</h1>

<p>Current render mode: @RendererInfo.RenderMode</p>

<button @onclick="Increment">Count: @count</button>

@code {
    private int count = 0;

    private void Increment()
    {
        count++;
    }
}

Choosing the Right Rendering Mode

Selecting the appropriate rendering mode depends on your application's requirements. Here's a decision guide:

• Static SSR: Use for content pages that don't need interactivity (blogs, documentation, landing pages). Best for SEO and fast initial load.
• Interactive Server: Use for real-time applications (dashboards, chat, collaborative editing) where server-side processing is needed and low latency is acceptable.
• Interactive WebAssembly: Use for client-heavy applications (games, offline tools, complex calculators) where you want to offload processing to the client and reduce server costs.
• Interactive Auto: Use for applications that need a balance between initial load time and interactivity, especially when you expect users to visit multiple pages (e.g., e-commerce sites).

You can also mix modes within a single page. For example, a product listing page can be Static SSR for the list, but each product card can have an Interactive Server 'Add to Cart' button. This is known as 'islands architecture'.

@page "/products"
@rendermode RenderMode.Static

<h1>Products</h1>

@foreach (var product in products)
{
    <div class="product-card">
        <h3>@product.Name</h3>
        <p>@product.Description</p>
        <AddToCartButton ProductId="@product.Id" />
    </div>
}

@code {
    private List<Product> products = new();

    protected override async Task OnInitializedAsync()
    {
        // Load products from database
        products = await ProductService.GetAllAsync();
    }
}

Debugging Rendering Mode Issues

Debugging rendering mode issues can be tricky because the behavior differs between development and production. Here are common issues and how to resolve them:

Issue: Component not interactive - Check that the component has an interactive render mode (InteractiveServer, InteractiveWebAssembly, or InteractiveAuto). Static SSR components cannot handle events. - Verify that the render mode is not overridden by a parent component. Use the browser's developer tools to inspect the HTML; interactive components will have additional attributes (e.g., blazor-server).

Issue: Slow initial load - For Interactive WebAssembly, consider using InteractiveAuto to provide a fast initial load with Server mode while downloading WebAssembly assets. - Enable prerendering for InteractiveServer and InteractiveAuto modes to speed up perceived load time.

Issue: State lost on navigation - When using InteractiveAuto, state is not preserved when switching from Server to WebAssembly. Implement a state container service that persists state in browser storage (e.g., ProtectedLocalStorage). - For InteractiveServer, state is preserved as long as the circuit is alive. If the circuit disconnects, state is lost. Implement reconnection logic.

Issue: High server resource usage - Switch from InteractiveServer to InteractiveWebAssembly for less interactive pages. - Use Static SSR for content pages. - Scale out your server or use Azure SignalR Service.

To debug rendering modes, use the RendererInfo service to log the current mode:

@inject RendererInfo RendererInfo @code { protected override void OnInitialized() { Console.WriteLine($"Render mode: {RendererInfo.RenderMode}"); } }

@page "/debug"
@rendermode InteractiveAuto
@inject RendererInfo RendererInfo
@inject ILogger<DebugRenderingMode> Logger

<h1>Debug Rendering Mode</h1>

<p>Current mode: @RendererInfo.RenderMode</p>
<p>Is interactive: @RendererInfo.IsInteractive</p>

<button @onclick="LogMode">Log Mode</button>

@code {
    private void LogMode()
    {
        Logger.LogInformation("Current render mode: {Mode}", RendererInfo.RenderMode);
    }
}