Blazor Basics: Prerendering Server Components in Blazor

Learn how prerendering in Blazor Server works and why disabling prerendering isn’t the best option.

When I first encountered prerendering, I made many mistakes. I didn’t understand how prerendering in Blazor Server worked. I defaulted to disabling prerendering and ignored it completely.

With more experience, I learned that prerendering in Blazor Server is helpful in providing a better user experience. Another benefit of using prerendering is that it can affect search engine optimization (SEO) in a positive way because the first rendering performance will increase.

In this article, I will explain everything you need to know about prerendering in Blazor Server to help you get the most out of it and avoid making the same mistake I did.

Static Server Rendering (SSR) and Stream Rendering

Starting with .NET 8, static server rendering (SSR) and stream rendering are the default. If we do not specify Blazor Server or Blazor WebAssembly as the interactivity mode, Blazor will run in SSR mode.

Stream rendering is an additional option for SSR and allows the sending of data from the server to the client when it arrives within the same request.

SSR and stream rendering have nothing to do with Blazor Server or prerendering in Blazor Server. It’s essential to make the distinction.

A Typical Example Page

For this example, I will use a simple Blazor page component that performs a typical task. It loads data from a service (that could load it from a database) and renders it on the screen.

I use the all-time player statics of the National Hockey League (NHL) and display the player’s name, number of games played and number of points scored.

@page "/"
@inject IStatsService StatsService;
@using BlazorServerPrerendering.Services

<PageTitle>NHL All Time Most Points Scored</PageTitle>

<h1>NHL All Time Most Points Scored</h1>
<table>
    <thead>
        <tr>
            <th style="width: 180px;">Name</th>
            <th style="width: 140px;">Games Played</th>
            <th style="width: 140px;">Points Scored</th>
        </tr>
    </thead>
    <tbody>
        @foreach (var player in Players)
        {
            <tr>
                <td>@player.Name</td>
                <td>@player.GamesPlayed</td>
                <td>@player.Points</td>
            </tr>
        }
    </tbody>
</table>

@code {
    public IEnumerable<Player> Players { get; set; } = new List<Player>();

    protected async override Task OnInitializedAsync()
    {
        Players = await StatsService.GetMostCareerPoints();
    }
}

The StatsService implementation looks like this:

namespace BlazorServerPrerendering.Services;

public class StatsService : IStatsService
{
    public async Task<IEnumerable<Player>> GetMostCareerPoints()
    {
        await Task.Delay(2500);

        return new List<Player>
        {
            new Player("Wayne Gretzky", 1487, 2857),
            new Player("Jaromir Jagr", 1733, 1921),
            new Player("Mark Messier", 1756, 1887),
            new Player("Gordie Hower", 1767, 1850),
            new Player("Ron Francis", 1731, 1798),
            new Player("Marcel Dionne", 1348, 1771),
            new Player("Steve Yzerman", 1514, 1755),
            new Player("Mario Lemieux", 915, 1723),
            new Player("Joe Sakic", 1378, 1641),
            new Player("Sidney Crosby", 1272, 1596)
        };
    }
}

You can access the code used in this example on GitHub.

Blazor Server with Prerendering Disabled

First, let’s discuss the behavior of a Blazor Server page component with prerendering disabled.

As a quick reminder, you can disable prerendering for Blazor Server interactivity globally when using the latest .NET 8 Blazor Web App project template in the App.razor file:

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

You can also disable prerendering on a per-component basis.

When I start the example application, I get the following HTML response to the page request:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <base href="/">
        <link rel="stylesheet" href="bootstrap/bootstrap.min.css">
        <link rel="stylesheet" href="app.css">
        <link rel="stylesheet" href="BlazorServerPrerendering.styles.css">
        <link rel="icon" type="image/png" href="favicon.png">
    </head>
    <body>
        <script src="_framework/blazor.web.js"></script>
        <script type="text/javascript" src="/_vs/browserLink" async="async" id="__browserLink_initializationData" data-requestId="87d1b4f53dcb49c2bbceff7bcec1a36b" data-requestMappingFromServer="false" data-connectUrl="http://localhost:51174/dc88d2a6c0df4143a162fcf28535f3bb/browserLink"></script>
        <script src="/_framework/aspnetcore-browser-refresh.js"></script>
    </body>
</html>

As you can see, we get the head section and the scripts and stylesheet references. However, we do not see any content in the HTML body section.

Now let’s inspect the messages sent via the SignalR connection. There are many messages exchanged, but when we look for the messages with the biggest length, we see a message with 3.5 kb in size.

When I look at the data transmitted, I can spot the “Games Played” and “Points Scored” text. This means that the page structure is sent through the SignalR connection.

A few messages later, we see another interesting message with the length of 3.0 kb. When exploing its content, we see that the table content with the player stats is sent in this message.

In conclusion: With prerendering disabled, only the bare essentials are transmitted as part of the HTTP response. The whole content of the page is split into two SignalR messages. It means that as long as the SignalR connection hasn’t been established, the user will not see any content on the screen.

Blazor Server with Prerendering Enabled

Now, let’s enable prerendering for this page component and inspect the difference in behavior.

We change the code in the App.razor component to enable prerendering globally.

<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: true)" />
<Routes @rendermode="new InteractiveServerRenderMode(prerender: true)" />

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <base href="/">
        <link rel="stylesheet" href="bootstrap/bootstrap.min.css">
        <link rel="stylesheet" href="app.css">
        <link rel="stylesheet" href="BlazorServerPrerendering.styles.css">
        <link rel="icon" type="image/png" href="favicon.png">
        <!--Blazor:{"type":"server","prerenderId":"c05921b093c54e259972ce1b81dbf6c3","key":{"locationHash":"(omitted):5","formattedComponentKey":""},"sequence":0,"descriptor":"(omitted)"}-->
        <title>NHL All Time Most Points Scored</title>
        <!--Blazor:{"prerenderId":"c05921b093c54e259972ce1b81dbf6c3"}-->
    </head>
    <body>
        <!--Blazor:{"type":"server","prerenderId":"806478d819ec4328ba0776e3f00edd0e","key":{"locationHash":"(omitted):8","formattedComponentKey":""},"sequence":1,"descriptor":"(omitted)"}-->
        <div class="page" b-afgyb8e6cv>
            <div class="sidebar" b-afgyb8e6cv>
                <!-- ommited for clarity -->
            </div>
            <main b-afgyb8e6cv>
                <article class="content px-4" b-afgyb8e6cv>
                    <h1>NHL All Time Most Points Scored</h1>
                    <table>
                        <thead>
                            <tr>
                                <th style="width: 180px;">Name</th>
                                <th style="width: 140px;">Games Played</th>
                                <th style="width: 140px;">Points Scored</th>
                            </tr>
                        </thead>
                        <tbody></tbody>
                    </table>
                </article>
            </main>
        </div>
        <div id="blazor-error-ui" b-afgyb8e6cv>
            An unhandled error has occurred.
    <a href class="reload" b-afgyb8e6cv>Reload</a>
            <a class="dismiss" b-afgyb8e6cv>🗙</a>
        </div>
        <script src="_framework/blazor.web.js"></script>
        <script type="text/javascript" src="/_vs/browserLink" async="async" id="__browserLink_initializationData" data-requestId="e703734d73c14a95b38326c1c380c3e4" data-requestMappingFromServer="false" data-connectUrl="http://localhost:51174/dc88d2a6c0df4143a162fcf28535f3bb/browserLink"></script>
        <script src="/_framework/aspnetcore-browser-refresh.js"></script>
    </body>
</html>

As you can see, this time we get a lot more information in the body section of the HTML response to the initial page request. We get the table definition including the table headers.

Notice the Blazor placeholder comments, including a prerenderId, indicating that this part of the page will be replaced when the full page load has been completed.

Hint: For clarity, I omitted some of the GUIDs used. You can explore the full HTTP response when running the example application yourself.

Now, let’s see how the player statistics are transferred from the server to the client.

Again, we open the developer tools to inspect the messages sent over the SignalR connection. Similar to prerendering disabled, the player data is transmitted via a SignalR message.

This part remains the same since, with Blazor Server interactivity, we leverage a SignalR connection to communicate with the client.

Benefits of Prerendering in Blazor Server

With prerendering, Blazor Server sends a rendered HTML page from the server to the client without enabling event handlers.

On the upside, the server sends the HTML user interface as part of the initial HTTP response to the user as quickly as possible. The user experience is improved because the web application feels more responsive.

Prerendering can also improve SEO because crawlers can calculate their speed rankings based on the initial response. With prerendering disabled, a crawler is not able to see the structure of a page because it does not establish a SignalR connection.

On the downside, once the page is fully loaded, Blazor Server sends an update through its SignalR connection, and parts of the user interface are replaced with new content. After this step, event handlers are enabled and the application reacts to user input, such as pressing a button.

It also means that until the event handlers are enabled, the app does not react to user input, such as button clicks or other interactivity. With prerending, the client gets an initial HTML response even though the SignalR connection has yet to be established.

As mentioned in the introduction of this article, this mainly benefits the application’s responsiveness and, therefore, positively impacts the search engine rankings.

It’s especially important for public-facing applications and websites and might be less relevant to internal applications. However, internal applications also greatly benefit from better responsiveness.

The effect of prerendering becomes increasingly measurable as the time span between the initial render (prerendering) and establishing the SignalR connection grows. This could be the case when the application is under heavy load or the latency between the server and the client is high.

The Problem with Prerendering: OnInitializedAsync Is Called Twice

There is a well-known problem when working with prerendering. The OnInitializedAsync lifecycle method is called twice. The first time when the page is prerendered on the server, and the second time when the page is rendered with Blazor Server interactivity through the SignalR connection.

Most developers decide to disable prerendering because of this issue. And I fully understand it. I did the same until I fully understood prerendering.

Now that I see the benefits of prerendering, I still need to find a solution to prevent the service from being called twice. I simply don’t want to load the data from the database twice on every page load.

Blazor provides the PersistentComponentState type to handle this issue. There are other caching strategies, but I will focus on the one mentioned in the Microsoft documentation.

The idea is that we store the state from the first service call and reuse it during the second call instead of calling the service a second time.

Let’s see how we integrate the PersistentComponentState type into our page to prevent the service from being called twice.

@inject PersistentComponentState ApplicationState
@implements IDisposable

In the page component, we inject an instance of the PersistentComponentState type and add the @implements directive for the IDisposable type.

private PersistingComponentStateSubscription _persistingSubscription;

Next, we add a new instance variable of type PersistingComponentStateSubscription. It provides us with an interface to store and load Blazor component state.

protected async override Task OnInitializedAsync()
{
    _persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);

    var statedLoaded = ApplicationState.TryTakeFromJson<IEnumerable<Player>>("players", out var players);

    Players = statedLoaded && players != null ? players : await StatsService.GetMostCareerPoints();
}

The OnInitializeAsync method now looks different. First, we use the instance variable of type PersistingComponentStateSubscription to register the PersistData callback method. The method will be triggered by the Blazor framework when the component is rendered.

Next, we use the ApplicationState object to access the state stored for the players key. The return statement first checks whether there was state loaded and that the state is not null. If the check returns true, we return the loaded application state. Otherwise, we access our service and load the data.

private Task PersistData()
{
    ApplicationState.PersistAsJson("players", Players);
    return Task.CompletedTask;
}

The PersistData method uses the ApplicationState object and persists the data stored in the instance variable Players. Again, this method will be called by the Blazor framework when the component rendered.

public void Dispose()
{
    _persistingSubscription.Dispose();
}

Last but not least, we remove the callback method from the PersistingComponentStateSubscription when disposing the Blazor component instance.

It’s important to dispose of the callback. Otherwise, you’ll end up with a memory leak since the callback will remain registered even though the component itself has been garbage-collected.

I know this method currently requires a lot of code. I wish it was simpler. However, this is the standard way to use prerendering in Blazor Server and avoiding duplicated service calls in the OnInitializedAsync method. And once you get used to the pattern, it isn’t that hard to implement.

Be Aware of Enhanced Navigation in .NET 8

With .NET 8, Blazor introduced enhanced navigation. When enabled, prerendering does not occur during internal navigation. Instead, the content will be delivered through the (already opened) SignalR connection.

If you want to test the prerendering behavior of a Blazor Server page, a full page load is required.

Conclusion

We learned what prerendering in Blazor Server is and how to take advantage of it to improve the user experience and possibly the search engine optimization of a Blazor web application.

We learned the differences between using Blazor Server interactivity with prerendering enabled and disabled.

We learned how to properly implement service calls inside the OnInitializedAsync lifecycle method to avoid duplicated service calls by leveraging the PersistentComponentState and PersistingComponentStateSubscription types.

You can access the code used in this example on GitHub.

If you want to learn more about Blazor development, you can watch my free Blazor Crash Course on YouTube. And stay tuned to the Telerik blog for more Blazor Basics.