Edit

Persist Component State Tag Helper in ASP.NET Core

  • Article

Prerequisites

Follow the guidance in the Configuration section for either:

Persist state for prerendered components

To persist state for prerendered components, use the Persist Component State Tag Helper (reference source). Add the Tag Helper's tag, <persist-component-state />, inside the closing </body> tag of the _Host page in an app that prerenders components.

Note

Documentation links to .NET reference source usually load the repository's default branch, which represents the current development for the next release of .NET. To select a tag for a specific release, use the Switch branches or tags dropdown list. For more information, see How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205).

In Blazor WebAssembly apps (Pages/_Host.cshtml):

<body>
    <component type="typeof(App)" render-mode="WebAssemblyPrerendered" />

    ...

    <persist-component-state />
</body>

In Blazor Server apps (Pages/_Host.cshtml):

<body>
    <component type="typeof(App)" render-mode="ServerPrerendered" />

    ...

    <persist-component-state />
</body>

Decide what state to persist using the PersistentComponentState service. PersistentComponentState.RegisterOnPersisting registers a callback to persist the component state before the app is paused. The state is retrieved when the application resumes.

In the following example:

  • The {TYPE} placeholder represents the type of data to persist (for example, WeatherForecast[]).
  • The {TOKEN} placeholder is a state identifier string (for example, fetchdata).
@implements IDisposable
@inject PersistentComponentState ApplicationState

...

@code {
    private {TYPE} data;
    private PersistingComponentStateSubscription persistingSubscription;

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

        if (!ApplicationState.TryTakeFromJson<{TYPE}>(
            "{TOKEN}", out var restored))
        {
            data = await ...;
        }
        else
        {
            data = restored!;
        }
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson("{TOKEN}", data);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

For more information and a complete example, see Prerender and integrate ASP.NET Core Razor components.

Prerendered state size and SignalR message size limit

This section only applies to Blazor Server apps.

A large prerendered state size may exceed the SignalR circuit message size limit, which results in the following:

  • The SignalR circuit fails to initialize with an error on the client: Circuit host not initialized.
  • The reconnection dialog on the client appears when the circuit fails. Recovery isn't possible.

To resolve the problem, use either of the following approaches:

  • Reduce the amount of data that you are putting into the prerendered state.
  • Increase the SignalR message size limit. WARNING: Increasing the limit may increase the risk of Denial of service (DoS) attacks.

Additional resources