The Evolution of Blazor: A Deep Dive into the Unified Architecture of ASP.NET Core 8

Executive Summary: The Blazor Revolution in.NET 8

With the release of.NET 8, Blazor has undergone a monumental architectural transformation, shifting from a collection of distinct hosting models to a unified, flexible framework centered on the concept of component render modes. This change marks a significant step forward, simplifying the developer experience while providing unprecedented control over application performance and behavior. The new Blazor Web App template now serves as the single starting point for all web development, consolidating the functionalities of previously separate project types.

The new architecture’s core principle is the ability to choose how and where each individual component is rendered, rather than being locked into a single paradigm for the entire application. This is achieved through a set of powerful features, including Static Server-Side Rendering (Static SSR), which provides a fast and SEO-friendly default, and progressive enhancements like enhanced navigation and streaming rendering that make static pages feel dynamic. The framework’s ability to seamlessly mix and match server-side and client-side logic on a per-component basis offers a new level of architectural flexibility, enabling developers to build highly optimized, full-stack web applications with C#.

Part I: The Foundational Shift: Blazor Web Apps and the Unified Project Model

The most significant change in the Blazor landscape within.NET 8 is the fundamental shift from a siloed hosting model paradigm to a unified, component-centric rendering architecture. This section deconstructs these core changes, explaining the new philosophy that underpins all modern Blazor development.

From Hosting Models to Render Modes: A New Paradigm

Prior to.NET 8, developers were required to choose one of three mutually exclusive hosting models at the start of a project: Blazor Server, Blazor WebAssembly, or Blazor Hybrid.¹ Each model represented a distinct architectural approach, and mixing them within a single web application was not a native capability. This created a rigid structure that often forced developers to make trade-offs between performance, scalability, and code security from the outset of development.

The.NET 8 release abandons this rigid model in favor of a new, more flexible approach. Developers now create a single Blazor Web App and, on a per-component or per-page basis, apply a “render mode” to dictate its behavior.² This conceptual shift from “hosting models” to “render modes” is a core tenet of the new architecture, allowing developers to combine the best aspects of server-side and client-side rendering within a single, cohesive solution.

The Blazor Web App Template: The Single Starting Point

The new Blazor Web App template is a direct result of this unification. It consolidates the functionalities of the old Blazor Server and Blazor WebAssembly ASP.NET Core Hosted templates into a single project type.³ The old Blazor Server template has been removed entirely, signaling the deprecation of that standalone architectural style for new projects.¹

This new template provides a pre-configured starting point that includes essential components for routing, navigation, and layout management, reducing initial setup complexities and enabling developers to focus on core application logic.⁸ The application’s entry point,

Program.cs, is now configured to support multiple render modes, demonstrating the framework’s inherent flexibility from its core configuration.⁵ A typical

Program.cs file in a Blazor Web App will look similar to this, showing the registration of interactive server components:

C#

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorComponents()
   .AddInteractiveServerComponents();
var app = builder.Build();
app.MapRazorComponents<App>()
   .AddInteractiveServerRenderMode();
app.Run();

⁴⁰

Static Server-Side Rendering (Static SSR): The New Default

The default rendering mode for any component or page in a new Blazor Web App is Static Server-Side Rendering (Static SSR), if no other mode is explicitly specified.⁴ In this mode, the server renders the component into a static HTML payload and sends it to the browser as a complete document. Because the component’s state is not maintained and no persistent connection is established, the component is immediately disposed of after the HTML is delivered.³

This approach offers significant benefits, most notably a fast initial page load and excellent Search Engine Optimization (SEO) because search engine crawlers receive a fully rendered HTML page.⁸ The configuration is as simple as creating a standard .razor component with no explicit render mode set.

Razor CSHTML

@page "/"
<h1>My Blazor App</h1>
<nav class="nav-bar">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/about">About</a>
</nav>
<div class="main-content">
    @* Content for the current page *@
</div>

⁸

Progressive Enhancements to Static SSR

Static SSR is not a return to traditional web development, but rather a progressive framework for modern web applications. The framework offers features that transparently add advanced capabilities to static pages, allowing them to feel dynamic and interactive without a full page refresh.

Enhanced Navigation and Form Handling: Blazor in.NET 8 enhances the user experience by intercepting navigation requests and form submissions. Instead of triggering a full page refresh, the Blazor script uses a fetch request to retrieve the new content and then efficiently patches the rendered response into the browser’s Document Object Model (DOM).³ This preserves more of the page’s state, resulting in a smoother, more fluid Single-Page Application (SPA)-like experience. A navigation component that utilizes enhanced navigation is simply a standard anchor tag:

@page "/"
<h1>My Blazor App</h1>
<nav class="nav-bar">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/about">About</a>
</nav>

Streaming Rendering: This powerful feature addresses the performance challenge of long-running asynchronous data loads. With streaming rendering, a page can render a fast initial layout with placeholder content while a database query or other lengthy operation runs in the background. Once the asynchronous operation completes, the updated content is streamed to the client on the same HTTP response connection and seamlessly patched into the DOM, improving the user’s perception of speed and responsiveness.⁷ You can enable this by applying the “ attribute to the component.C#

@page "/streaming-example"
@attribute

<h1>Streaming Rendering Example</h1>
<p>The time is: @currentCount</p>

@code {
    private int currentCount = 0;

    protected override async Task OnInitializedAsync()
    {
        await Task.Delay(5000); // Simulate a long-running data fetch
        currentCount = 100;
    }
}

Part II: Deconstructing the Blazor Rendering Engine

A deep understanding of how Blazor manages and updates the UI is fundamental to building high-performance applications. This section examines the low-level mechanics that drive the Blazor framework, specifically its DOM abstraction and the diffing algorithm.

The RenderTree: Blazor’s DOM Abstraction

Blazor does not directly manipulate the browser’s DOM. Instead, it uses a lightweight, in-memory C# abstraction called the RenderTree.¹¹ This tree-like data structure is a replica of the DOM’s current state and is designed to be updated far more efficiently than the browser’s native DOM.

The process of building this tree begins with the Razor compiler. When a .razor component is created, the compiler converts its markup into a C# class that inherits from ComponentBase and contains an overridden BuildRenderTree method.¹¹ This method then programmatically constructs the

RenderTree by translating the component’s markup into a series of RenderTree objects.

The Diffing Algorithm: The Engine of Efficiency

The efficiency of Blazor’s UI updates is attributed to its sophisticated diffing algorithm. When a component’s state changes, a new RenderTree is built. The algorithm then compares this new tree with the previous one to identify the minimal set of changes required to update the UI.¹¹ This set of changes, or “diff,” is then used to apply surgical updates to the browser’s DOM, avoiding the computationally expensive process of destroying and recreating entire subtrees.

The effectiveness of this algorithm can be influenced by the developer. In scenarios involving lists or collections, such as in a @foreach block, the @key directive can be used to provide the diffing algorithm with a unique identifier for each item.¹¹ This helps the algorithm track changes more accurately, ensuring that elements are correctly reordered, added, or removed without needlessly re-rendering the entire list, which can significantly improve performance.

Feature	Static SSR	Interactive Server	Interactive WebAssembly	Interactive Auto
Render Location	Server	Server	Client	Server, then client
Interactivity	No	Yes (via SignalR)	Yes (via WebAssembly)	Yes (starts with SignalR, then WebAssembly)
Initial Load	Fastest (static HTML)	Fast (small payload)	Slow (large download)	Fast (starts with Server)
Runtime Performance	N/A	Dependent on network latency	Near-native speed with AOT	Near-native speed after first load
Code Security	Code remains on server	Code remains on server	Code is downloaded to client	Code is downloaded to client
Offline Support	No	No	Yes	Yes (after first load)
Use Cases	Blogs, marketing sites	Dashboards, real-time apps	PWAs, offline-first apps	Highly interactive apps needing fast initial load

Part III: In-Depth Analysis of Blazor Render Modes

The new Blazor Web App template enables four distinct render modes, each with its own architectural considerations, advantages, and limitations.

Static Server-Side Rendering (Static SSR)

As discussed, Static SSR is the default and simplest mode, ideal for content that does not require interactivity, such as static pages, blogs, or marketing content.⁵ The architecture is straightforward: the server generates a static HTML payload and delivers it to the browser. There is no client-side.NET runtime and no persistent connection. This makes it extremely fast and beneficial for SEO, as search engine crawlers receive a fully rendered page.³

Interactive Server-Side Rendering (Interactive Server)

This mode represents the modern evolution of the old Blazor Server model. Components are executed on the server, but a persistent, real-time connection is established with the browser using SignalR over WebSockets.² When a user interacts with the UI, a UI event is sent over this connection to the server. The server processes the event, re-renders the component, calculates a DOM diff, and sends the minimal changes back to the client.

• Advantages: The initial download size is small, leading to a fast load time.² The application has full access to server capabilities and APIs, and the C# code remains secure on the server, hidden from the client.² This model also supports thin clients and browsers that do not support WebAssembly.²
• Limitations: A key drawback is the higher latency resulting from the network hop required for every user interaction.² The model provides no offline support, and scaling for a large number of concurrent users requires significant server resources to manage the persistent client connections and state.²

To apply this render mode, you use the @rendermode directive, either within the component itself or at the call site when using the component instance. ⁵

Razor CSHTML

@page "/interactive-server"
@rendermode InteractiveServer

<h1>Interactive Server Example</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++;
    }
}

⁵

Interactive WebAssembly (Interactive WebAssembly)

This mode is the successor to the original Blazor WebAssembly hosting model. The entire.NET runtime and application code are downloaded to the client’s browser, where they execute within a WebAssembly sandbox.² All interactivity occurs on the client, without a continuous connection to the server.

• Advantages: This model supports offline functionality, and since the work is offloaded to the client, it frees up server resources and allows for serverless deployment scenarios, such as hosting from a Content Delivery Network (CDN).²
• Limitations: The initial download size is larger, which can lead to a slower initial page load.² Additionally, components are limited to the capabilities of the browser, and since the code is sent to the client, it is not as secure as the server-side model and is susceptible to inspection and tampering.²

Interactive Auto Rendering (Interactive Auto)

The Interactive Auto render mode is a new hybrid model designed to provide the best user experience. A component configured for this mode initially renders as an Interactive Server component, ensuring a fast initial load.² While the user interacts with this server-side component, the necessary WebAssembly assets are downloaded and cached in the background. On subsequent visits to the same page, the component will bypass the server and run directly as an Interactive WebAssembly component, providing a fast, client-side experience with no network latency.⁴

This model, while offering a superior user experience, introduces a new layer of architectural complexity that developers must manage carefully. Components configured for Interactive Auto must be capable of running on both the server and the client.¹⁷ This means a component cannot contain code with dependencies that are specific to the server-side environment, such as direct database access or file system operations. To build truly agnostic components, developers must adopt architectural patterns like the Generic Repository Pattern and Dependency Injection to abstract away data access and other server-specific services.¹⁹ The requirement for a separate client project to hold the WebAssembly components further adds to the project’s structural complexity.⁵ This disciplined architectural approach is essential for effectively leveraging the power of Interactive Auto rendering.

Part IV: Common Problems and Expert Workarounds

New Blazor developers often encounter specific challenges related to the framework’s architecture and lifecycle. Understanding these common problems and their solutions is crucial for building robust and efficient applications.

The Prerendering Double-Call

One of the most common surprises for new developers is that a component’s OnInitializedAsync method can be called twice.²¹ This happens when a component is configured for interactive rendering with prerendering enabled (which is the default). The first call occurs on the server during the initial static render, and the second call happens when the interactive circuit is established on the client.²¹ If this method contains an expensive operation like fetching data from a database, that operation will be executed twice, which can significantly slow down the initial render and consume unnecessary resources.²⁵

Workaround: Using PersistentComponentState

The recommended solution is to use the PersistentComponentState service to save the data from the first server-side render and restore it for the second interactive render.²⁶ This prevents the data-fetching operation from being executed a second time.

C#

@page "/"
@implements IDisposable
@inject PersistentComponentState ApplicationState

<h1>Data Persistence Example</h1>
<p>Data loaded: @data</p>

@code {
    private string? data;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
        if (!ApplicationState.TryTakeFromJson<string>("DataToPersist", out var restoredData))
        {
            // First render, fetch data from an expensive source
            await Task.Delay(1000); // Simulate network latency
            data = "This is the fetched data.";
        }
        else
        {
            // Second render, restore data from the persistent state
            data = restoredData;
        }
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson("DataToPersist", data);
        return Task.CompletedTask;
    }

    void IDisposable.Dispose() => persistingSubscription.Dispose();
}

²⁶

UI Flicker During Prerendering

Another related issue is a noticeable “flicker” on the UI. This happens when the static HTML from the server is replaced by the interactive component after it loads, often resulting in a visual shift if the component’s final appearance differs from its initial static state. This can be caused by the double-call of OnInitializedAsync if the data isn’t persisted.²⁷

Workaround: Disable Prerendering or Persist State

The solution is to either disable prerendering for the component entirely or, more preferably, use the PersistentComponentState service to ensure a seamless transition.²⁹

You can disable prerendering for a specific component instance by passing the prerender flag to the render mode.

Razor CSHTML

<Counter @rendermode="new InteractiveServerRenderMode(prerender: false)" />

²⁹

Part V: Lifecycle, State Management, and Data Flow

Understanding the component lifecycle and data flow mechanisms is crucial for building robust and predictable Blazor applications.

The Blazor Component Lifecycle: A Walkthrough

Every Blazor component follows a defined lifecycle with a series of synchronous and asynchronous methods that can be overridden to execute logic at specific points:

• OnInitialized{Async}: This method is the entry point for a component, called once for the entire lifetime of the component instance. It is the ideal place for one-time initialization logic, such as fetching data that does not depend on component parameters.¹⁰
• OnParametersSet{Async}: This method is called after OnInitializedAsync and is subsequently invoked whenever the component receives new parameter values from its parent. This is the recommended location for initialization logic that is dependent on parameter values.¹⁰
• OnAfterRender{Async}: This method is called after a component has been rendered and the UI has been updated in the browser’s DOM. It is the appropriate place for any operations that require interaction with the rendered DOM elements, such as calling JavaScript interop functions.¹⁰

The Prerendering Dilemma: The Double-Call of OnInitializedAsync

The prerendering feature in Blazor, while beneficial for performance, introduces a significant challenge: the OnInitializedAsync method is called twice for components that are prerendered.²¹ The first call occurs during the initial static server-side render, and the second occurs when the interactive circuit is established. If an expensive data-fetching operation is placed in this method, it will be executed twice, slowing down the initial render and consuming unnecessary resources.²⁵

To address this, developers must explicitly manage the state to prevent duplicate work. The official solution is to use the PersistentComponentState service.²⁶ This service allows developers to save state (e.g., fetched data) from the initial render and restore it for the second, interactive render. This prevents unnecessary re-fetching and eliminates the “flicker” effect that occurs when the prerendered UI is replaced by the interactive component. State can be persisted declaratively using the “ attribute or manually by calling PersistentComponentState.RegisterOnPersisting.²⁷

State Management and Scoped Services

For components running in the Interactive Server mode, user state is maintained on the server. Each browser tab or screen session is associated with a “circuit,” which holds the component hierarchy and any dependency injection services with a “Scoped” lifetime.² If a client’s connection is temporarily lost, Blazor can attempt to reconnect them to their original circuit and state. The

PersistentComponentState service is an essential tool in this environment, as it allows developers to persist state across temporary circuit disconnections or when the application needs to gracefully pause inactive circuits.³

Data Binding and Component Communication

Blazor supports both one-way and two-way data binding. One-way binding is used to render data in a read-only fashion, simply by using the @ symbol followed by the property name.³⁰ Two-way binding allows for bidirectional data flow between the UI and the C# data model. The

@bind shorthand syntax for input elements is a common example, which automatically binds a property to the element’s value and handles the onchange event to update the property.³⁰ For custom components, the @bind syntax is syntactic sugar for a [Parameter] property (e.g., Value) and a corresponding EventCallback property with the name ValueChanged.³²

Here is a simple example of one-way binding:

Razor CSHTML

<h1>@Title</h1>
@code {
    public string Title { get; set; } = "One-Way Binding";
}

³⁰

And here is an example of two-way binding with a standard HTML input element:

Razor CSHTML

<input @bind="Username" />
<p>You typed: @Username</p>

@code {
    public string Username { get; set; } = string.Empty;
}

³¹

For custom components, the two-way binding convention requires a [Parameter] and a corresponding EventCallback. ³²

Razor CSHTML

<input type="number" @bind="Value" @bind:after="OnValueChanged" />

@code {
    [Parameter]
    public int Value { get; set; }

    [Parameter]
    public EventCallback<int> ValueChanged { get; set; }

    private async Task OnValueChanged()
    {
        await ValueChanged.InvokeAsync(Value);
    }
}

⁴¹

Data flow between parent and child components is a core aspect of Blazor. Data is passed down from a parent to a child component using the [Parameter] attribute.³² The child component can then communicate an event or a change in a value back up to the parent using an EventCallback.³²

Dependency Injection

Dependency Injection (DI) is a fundamental feature of Blazor, allowing services to be configured in a central location and injected into components.²⁰ Services are registered with a specific lifetime—Transient, Scoped, or Singleton—each with distinct implications for state management within the application.²⁰ Services can be injected into a component using the @inject Razor directive or the [Inject] attribute on a property.²⁰ A new feature in.NET 8 is support for “keyed services,” which enables the scoping of service registration and consumption using a unique key with the [Inject] attribute.³

Here are examples of injecting services using both @inject and the [Inject] attribute:

Razor CSHTML

@inject IMyService MyService

@code {
    [Inject]
    public IMyService MyService { get; set; }
}

²⁰

.NET 8 also introduces Keyed Dependency Injection, allowing you to register multiple implementations of an interface and inject the correct one using a key. ⁴²

C#

// Program.cs
builder.Services.AddKeyedSingleton<ICar, SuvService>("SUV");
builder.Services.AddKeyedSingleton<ICar, SedanService>("Sedan");

// Component.cs (code-behind file)
public partial class MyComponent
{
   
    public ICar SuvCar { get; set; }
}

⁴²

Part VI: Practical Considerations and Advanced Topics

This final section provides actionable advice and discusses advanced topics critical for building production-ready Blazor applications.

Performance Optimization Techniques

• Rendering Performance: Avoiding unnecessary rendering is key to a responsive UI. Blazor’s diffing algorithm is efficient, but developers can improve performance by using the ShouldRender method to control when a component re-renders. For large lists, the Virtualize<TItem> component can be used to only render the visible elements, significantly reducing overhead.¹⁰
• Payload Size Optimization: For WebAssembly apps, payload size is a critical performance factor. Blazor optimizes this by using the Intermediate Language (IL) Trimmer to strip unused code, compressing HTTP responses, and caching the.NET runtime and assemblies in the browser.²
• AOT Compilation: Ahead-of-Time (AOT) compilation is available for Blazor WebAssembly, which compiles.NET code directly into WebAssembly binaries. This can drastically improve runtime execution speed at the expense of a larger initial download size.²
• Algorithmic and.NET Optimizations: General C# and.NET best practices are crucial. This includes using efficient data structures like Dictionary for fast lookups, avoiding superlinear algorithms on large datasets, and leveraging asynchronous I/O to prevent the CPU from waiting on I/O operations.³⁷

Security Best Practices

• Authentication and Authorization: Blazor has built-in support for authentication and authorization. It is best practice to use ASP.NET Core Identity or external providers like Azure AD, enforcing role- or claims-based policies to control access to sensitive data and functionality.¹⁷
• Anti-Forgery:.NET 8 introduces new anti-forgery support for forms. Developers should use the AntiforgeryToken component and the “ attribute to protect against Cross-Site Request Forgery (CSRF) attacks.³
• Content Security Policy (CSP): A robust Content Security Policy (CSP) is essential to mitigate security risks. The framework’s architecture introduces unique considerations, particularly for Blazor Server. A large prerendered state can exceed the SignalR message size limit, potentially causing the circuit to fail. The documentation warns that increasing this limit could increase the risk of a Denial of Service (DoS) attack.¹⁵ Furthermore, when compression is enabled by default for Interactive Server components, a stricter frame-ancestors policy is required to prevent rendering untrusted data, which can leave the application vulnerable to attacks.¹⁵ These points highlight the importance of understanding the security implications of architectural decisions in the unified model.

JavaScript Interoperability (JS Interop)

While Blazor aims to minimize the need for JavaScript, interop is often necessary. Best practices for JS interop include:

• All interop calls are asynchronous by default to ensure compatibility across server and client rendering models.³⁹
• It is critical to avoid using JavaScript to directly mutate or manipulate elements in the DOM that Blazor controls, as this can lead to an inconsistent internal representation and undefined behavior.³⁹
• The use of inline event handlers is discouraged, as it mixes HTML and JavaScript and can be blocked by a Content Security Policy.³⁹

Conclusion: Expert Recommendations for Modern Blazor Development

The unified architecture in ASP.NET Core 8 fundamentally redefines Blazor development, empowering developers with unprecedented flexibility. The primary recommendation is to fully embrace this new model by starting all web projects with the Blazor Web App template.

1. Adopt Static SSR as the Default: Leverage Static SSR for all components that do not require interactivity. This provides a performant, SEO-friendly baseline that can be progressively enhanced with streaming rendering and enhanced navigation.
2. Use Interactive Auto for Interactive Components: For components that require user interaction, the Interactive Auto render mode offers the best of both worlds, providing a fast initial load and a seamless transition to a low-latency client-side experience.
3. Build Render-Mode-Agnostic Components: To effectively use the unified model, particularly the Interactive Auto mode, adopt a clean architectural approach with a strong separation of concerns. This means abstracting data access and business logic behind interfaces and using dependency injection to avoid hard-coding server-specific dependencies.
4. Prioritize State Management: Be mindful of the lifecycle of components and the dual execution of OnInitializedAsync during prerendering. Use the PersistentComponentState service to prevent unnecessary data fetching and ensure a smooth, flicker-free user experience.
5. Maintain a Continuous Focus on Performance and Security: The new architecture introduces specific performance and security considerations, such as managing payload size for WebAssembly and understanding the security risks associated with the SignalR connection in Blazor Server. A deep understanding of these nuances is essential for building robust, high-quality applications.

The Blazor Development Mindset

Blazor is not just another web framework; it represents a philosophical shift in how web applications can be built within the Microsoft ecosystem. A modern Blazor developer’s mindset should be rooted in a few key principles.

• Think in Components, Not Pages: Blazor’s core is a component-based architecture, similar to popular JavaScript frameworks like React and Angular.⁴⁴ The building blocks of an application are self-contained, reusable components, and the application is a tree of these components. This approach encourages modularity, reusability, and a clear separation of UI concerns, moving away from the page-centric model of older frameworks like ASP.NET Web Forms.⁴⁵
• Embrace the One-Stack Model: The framework’s fundamental premise is to enable developers to build full-stack web applications using a single language: C#.⁴⁶ This eliminates the context-switching and maintenance overhead of using separate languages and tools for the front end (JavaScript, TypeScript) and the back end (C#). For a developer familiar with C# and the.NET ecosystem, this provides a seamless and highly productive development experience.⁴⁶
• Choose the Right Tool for the Job: The new unified architecture and render modes in.NET 8 demand a new level of intentionality from developers. Instead of being locked into a single hosting model for the entire application, the modern mindset is to analyze the needs of each individual component and select the most appropriate render mode. Static SSR is ideal for content-heavy, non-interactive pages, while interactive modes should be reserved for components that require real-time user interaction.⁴⁴
• Adopt a Clean Architecture: To truly leverage the power of Blazor’s flexible rendering, components must be “render-mode-agnostic,” meaning they can function correctly on both the server and the client.¹⁸ This requires a disciplined architectural approach. Developers should separate their data access and business logic into a distinct layer and use dependency injection to provide services to their components. This ensures that the components themselves do not contain server-specific code, making them portable across render modes and more testable.¹⁹