Prerender ASP.NET Core Razor components

To preserve prerendered state, use the [SupplyParameterFromPersistentComponentState] attribute to persist state in properties. Properties with this attribute are automatically persisted using the PersistentComponentState service during prerendering. The state is retrieved when the component renders interactively or the service is instantiated.

By default, properties are serialized using the System.Text.Json serializer with default settings. Serialization isn't trimmer safe and requires preservation of the types used. For more information, see Configure the Trimmer for ASP.NET Core Blazor.

The following counter component persists counter state during prerendering and retrieves the state to initialize the component:

• The [SupplyParameterFromPersistentComponentState] attribute is applied to the CounterState type (State).
• The counter's state is assigned when null in OnInitialized and restored automatically when the component renders interactively.

PrerenderedCounter2.razor:

@page "/prerendered-counter-2"
@inject ILogger<PrerenderedCounter2> Logger

<PageTitle>Prerendered Counter 2</PageTitle>

<h1>Prerendered Counter 2</h1>

<p role="status">Current count: @State?.CurrentCount</p>

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

@code {
    [SupplyParameterFromPersistentComponentState]
    public CounterState? State { get; set; }

    protected override void OnInitialized()
    {
        if (State is null)
        {
            State = new() { CurrentCount = Random.Shared.Next(100) };
            Logger.LogInformation("CurrentCount set to {Count}", 
                State.CurrentCount);
        }
        else
        {
            Logger.LogInformation("CurrentCount restored to {Count}", 
                State.CurrentCount);
        }
    }

    private void IncrementCount()
    {
        if (State is not null)
        {
            State.CurrentCount++;
        }
    }

    public class CounterState
    {
        public int CurrentCount { get; set; }
    }
}

When the component executes, CurrentCount is only set once during prerendering. The value is restored when the component is rerendered. The following is example output.

info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
CurrentCount set to 96
info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
CurrentCount restored to 96

In the following example that serializes state for multiple components of the same type:

• Properties annotated with the [SupplyParameterFromPersistentComponentState] attribute are serialized and deserialized during prerendering.
• The @key directive attribute is used to ensure that the state is correctly associated with the component instance.
• The Element property is initialized in the OnInitialized lifecycle method to avoid null reference exceptions, similarly to how null references are avoided for query parameters and form data.

PersistentChild.razor:

<div>
    <p>Current count: @Element.CurrentCount</p>
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</div>

@code {
    [SupplyParameterFromPersistentComponentState]
    public State Element { get; set; }

    protected override void OnInitialized()
    {
        Element ??= new State();
    }

    private void IncrementCount()
    {
        Element.CurrentCount++;
    }

    private class State
    {
        public int CurrentCount { get; set; }
    }
}

Parent.razor:

@page "/parent"

@foreach (var element in elements)
{
    <PersistentChild @key="element.Name" />
}

In the following example that serializes state for a service:

• Properties annotated with the [SupplyParameterFromPersistentComponentState] attribute are serialized during prerendering and deserialized when the app becomes interactive.
• The AddPersistentService method is used to register the service for persistence. The render mode is required because the render mode can't be inferred from the service type. Use any of the following values:
  • RenderMode.Server: The service is available for the Interactive Server render mode.
  • RenderMode.Webassembly: The service is available for the Interactive Webassembly render mode.
  • RenderMode.InteractiveAuto: The service is available for both the Interactive Server and Interactive Webassembly render modes if a component renders in either of those modes.
• The service is resolved during the initialization of an interactive render mode, and the properties annotated with the [SupplyParameterFromPersistentComponentState] attribute are deserialized.

CounterService.cs:

public class CounterService
{
    [SupplyParameterFromPersistentComponentState]
    public int CurrentCount { get; set; }

    public void IncrementCount()
    {
        CurrentCount++;
    }
}

In Program.cs:

builder.Services.AddPersistentService<CounterService>(RenderMode.InteractiveAuto);

Serialized properties are identified from the actual service instance:

• This approach allows marking an abstraction as a persistent service.
• Enables actual implementations to be internal or different types.
• Supports shared code in different assemblies.
• Results in each instance exposing the same properties.

As an alternative to using the declarative model for persisting state with the [SupplyParameterFromPersistentComponentState] attribute, you can use the PersistentComponentState service directly, which offers greater flexibility for complex state persistence scenarios. Call PersistentComponentState.RegisterOnPersisting to register a callback to persist the component state during prerendering. The state is retrieved when the component renders interactively. Make the call at the end of initialization code in order to avoid a potential race condition during app shutdown.

The following counter component example persists counter state during prerendering and retrieves the state to initialize the component.

PrerenderedCounter3.razor:

@page "/prerendered-counter-3"
@implements IDisposable
@inject ILogger<PrerenderedCounter3> Logger
@inject PersistentComponentState ApplicationState

<PageTitle>Prerendered Counter 3</PageTitle>

<h1>Prerendered Counter 3</h1>

<p role="status">Current count: @currentCount</p>

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

@code {
    private int currentCount;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override void OnInitialized()
    {
        if (!ApplicationState.TryTakeFromJson<int>(
            nameof(currentCount), out var restoredCount))
        {
            currentCount = Random.Shared.Next(100);
            Logger.LogInformation("currentCount set to {Count}", currentCount);
        }
        else
        {
            currentCount = restoredCount!;
            Logger.LogInformation("currentCount restored to {Count}", currentCount);
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistCount);
    }

    private Task PersistCount()
    {
        ApplicationState.PersistAsJson(nameof(currentCount), currentCount);

        return Task.CompletedTask;
    }

    private void IncrementCount() => currentCount++;

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

When the component executes, currentCount is only set once during prerendering. The value is restored when the component is rerendered. The following is example output.

info: BlazorSample.Components.Pages.PrerenderedCounter3[0]
currentCount set to 96
info: BlazorSample.Components.Pages.PrerenderedCounter3[0]
currentCount restored to 96

To preserve prerendered state, decide what state to persist using the PersistentComponentState service. PersistentComponentState.RegisterOnPersisting registers a callback to persist the component state during prerendering. The state is retrieved when the component renders interactively. Make the call at the end of initialization code in order to avoid a potential race condition during app shutdown.

The following counter component example persists counter state during prerendering and retrieves the state to initialize the component.

PrerenderedCounter2.razor:

@page "/prerendered-counter-2"
@implements IDisposable
@inject ILogger<PrerenderedCounter2> Logger
@inject PersistentComponentState ApplicationState

<PageTitle>Prerendered Counter 2</PageTitle>

<h1>Prerendered Counter 2</h1>

<p role="status">Current count: @currentCount</p>

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

@code {
    private int currentCount;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override void OnInitialized()
    {
        if (!ApplicationState.TryTakeFromJson<int>(
            nameof(currentCount), out var restoredCount))
        {
            currentCount = Random.Shared.Next(100);
            Logger.LogInformation("currentCount set to {Count}", currentCount);
        }
        else
        {
            currentCount = restoredCount!;
            Logger.LogInformation("currentCount restored to {Count}", currentCount);
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistCount);
    }

    private Task PersistCount()
    {
        ApplicationState.PersistAsJson(nameof(currentCount), currentCount);

        return Task.CompletedTask;
    }

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

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

When the component executes, currentCount is only set once during prerendering. The value is restored when the component is rerendered. The following is example output.

info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
currentCount set to 96
info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
currentCount restored to 96