ASP.NET Core Blazor 预呈现状态持久化

本文介绍如何在 Blazor 应用中使用持久组件状态服务,在预呈现过程中保持组件状态。 你将了解如何直接使用 [PersistentState] 属性、 PersistentComponentState 服务,以及如何为持久性状态创建自定义序列化程序。

如果不保留组件状态,预呈现期间使用的状态将丢失,并且必须在应用完全加载时重新创建。 如果异步创建任何状态,则 UI 可能会闪烁,因为预呈现的 UI 将替换为临时加载内容,然后再次完全呈现。

请考虑以下 PrerenderedCounter1 计数器组件。 该组件在预呈现期间在 OnInitialized 生命周期方法中设置初始随机计数器值。 当组件以交互方式呈现时,第二次执行时 OnInitialized 将替换初始计数值。

PrerenderedCounter1.razor:

@page "/prerendered-counter-1"
@inject ILogger<PrerenderedCounter1> Logger

<PageTitle>Prerendered Counter 1</PageTitle>

<h1>Prerendered Counter 1</h1>

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

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

@code {
    private int currentCount;

    protected override void OnInitialized()
    {
        currentCount = Random.Shared.Next(100);
        Logger.LogInformation("currentCount set to {Count}", currentCount);
    }

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

注释

如果应用采用 交互式路由,并且通过内部 增强导航访问页面,则不会进行预呈现。 因此,必须为 PrerenderedCounter1 组件执行完整页面重载才能查看以下输出。 有关详细信息,请参阅 交互式路由和预呈现 部分。

运行应用并检查组件的日志记录。 下面是示例输出。

info: BlazorSample.Components.Pages.PrerenderedCounter1[0]
currentCount set to 41
info: BlazorSample.Components.Pages.PrerenderedCounter1[0]
currentCount set to 92

第一个记录的计数发生在预呈现期间。 重新呈现组件时,会在预呈现后再次设置计数。 当计数从 41 更新到 92 时,UI 也会闪烁。

为了在预呈现期间保留计数器的初始值,Blazor 支持使用 PersistentComponentState 服务在预呈现页面中保留状态(对于嵌入到 Razor Pages 或 MVC 应用的页面或视图中的组件,使用持久组件状态标记帮助程序)。

通过使用在预呈现期间使用的相同状态来初始化组件,将只执行一次成本高昂的初始化步骤。 呈现的 UI 也与预呈现 UI 相匹配,因此浏览器不会闪烁。

持久预呈现状态将传输到客户端,用于还原组件状态。 在客户端呈现(CSR)期间,InteractiveWebAssembly数据将暴露给浏览器,并且不得包含敏感的隐私信息。 在交互式服务器端呈现(交互式 SSR,InteractiveServer)期间,ASP.NET Core 数据保护可确保安全传输数据。 InteractiveAuto 呈现模式结合了 WebAssembly 和服务器交互性,因此有必要考虑向浏览器公开数据,就像在 CSR 案例中一样。

若要使用 PersistentComponentState 服务保留预呈现状态,请将 [PersistentState] 属性 应用于 public 属性。 当组件以交互方式呈现或实例化 PersistentComponentState 服务时,会检索状态。

使用 public 属性,因为框架将反射用于 剪裁未使用的代码 和 源生成等任务。

默认情况下,使用带有默认设置的序列化程序序列化 System.Text.Json 属性,并保存在预呈现 HTML 中。 序列化在修剪器中不安全,需要保留所用类型。 有关详细信息,请参阅 配置 ASP.NET Core 的 TrimmerBlazor。

以下计数器组件在预呈现期间保留计数器状态,并检索用于初始化组件的状态:

  • [PersistentState] 特性应用于类型为 CurrentCount 的公共可空 int? 属性。
  • 计数器状态在 null 中的 OnInitialized 时被赋值,并在组件以交互方式呈现时自动恢复。

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: @CurrentCount</p>

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

@code {
    [PersistentState]
    public int? CurrentCount { get; set; }

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

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

执行组件时,CurrentCount 仅在预呈现期间设置一次。 重新呈现组件时,会还原该值。 下面是示例输出。

注释

如果应用采用 交互式路由,并且通过内部 增强导航访问页面,则不会进行预呈现。 因此,必须为组件执行完整页面重载才能查看以下输出。 有关详细信息,请参阅 交互式路由和预呈现 部分。

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

在以下示例中,序列化同一类型的多个组件的状态:

  • 带有属性注释的公共属性将在预呈现期间进行序列化。
  • 指令@key属性用于确保状态与组件实例正确关联。
  • 该Element属性在OnInitialized生命周期方法中初始化,以避免出现 Null 引用异常,这与避免查询参数和表单数据中的 Null 引用类似。

PersistentChild.razor:

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

@code {
    [PersistentState]
    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" />
}

注释

用户配置的 JsonSerializerContext 不会流入 C# 联合反序列化。 请改用 [JsonUnion(TypeClassifier = typeof({TYPE CLASSIFIER}))],其中 {TYPE CLASSIFIER} 占位符是类型分类器。

序列化服务的状态

在以下示例中,序列化依赖项注入服务的状态:

  • 使用 [PersistentState] 属性 批注的属性在预呈现期间进行序列化,并在应用变为交互时进行反序列化。
  • 扩展 RegisterPersistentService 方法用于注册服务以保持持久性。 呈现模式是必需的,因为无法从服务类型推断呈现模式。 使用以下任何值:
    • RenderMode.Server:该服务可用于交互式服务器呈现模式。
    • RenderMode.Webassembly:该服务可用于交互式 Webassembly渲染模式。
    • RenderMode.InteractiveAuto:如果组件在任一模式下呈现,则服务同时可用于交互式服务器和交互式 Web 汇编呈现模式。
  • 服务在交互式呈现模式初始化时得到解决,并对带有[PersistentState]特性的属性进行反序列化。

注释

服务器上仅支持持久化作用域服务。 在 WebAssembly 客户端(InteractiveAuto 或 InteractiveWebAssembly 渲染模式)中,服务必须注册为 单例。 有关详细信息,请参阅 客户端项目服务注册 。

从实际服务实例标识序列化属性:

  • 此方法允许将抽象标记为持久服务。
  • 使实际实现可以是内部或不同类型的。
  • 支持在不同程序集中的共享代码。
  • 导致每个实例公开相同的属性。

以下计数器服务,将其当前计数属性标记为属性。 在预呈现期间,公共属性会被序列化;在应用变为交互状态后,无论服务注入到哪里,都会被反序列化。

CounterTracker.cs:

public class CounterTracker
{
    [PersistentState]
    public int CurrentCount { get; set; }

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

服务器项目服务注册

在服务端项目的 Program 文件中,注册作用域服务,并使用 RegisterPersistentService 注册持久化服务。 在以下示例中,如果组件在交互式服务器或交互式 WebAssembly 呈现模式下呈现,CounterTracker 服务会对这两种模式都可用,因为该服务已注册了 RenderMode.InteractiveAuto。

如果 Program 文件尚未使用 Microsoft.AspNetCore.Components.Web 命名空间,请将以下 using 语句添加到文件顶部:

using Microsoft.AspNetCore.Components.Web;

在服务器项目的 Program 文件中注册服务的位置:

builder.Services.AddScoped<CounterTracker>();

builder.Services.AddRazorComponents()
    .RegisterPersistentService<CounterTracker>(RenderMode.InteractiveAuto);

客户端项目服务注册

对于 RenderMode.InteractiveAuto 或 RenderMode.InteractiveWebAssembly,该服务还必须在 .Client 项目的 Program 文件中注册。 将其注册为单一实例,而不是作用域:

builder.Services.AddSingleton<CounterTracker>();

客户端 ComponentStatePersistenceManager 注册为单一实例,因此它从根服务提供程序解析其依赖项。 避免作用域服务注册。 如果服务在客户端上错误地注册为作用域,则从根提供程序解析它会在开发环境中引发 DirectScopedResolvedFromRootException。 除了异常之外,作用域注册在客户端上产生两个单独的实例:一个在状态还原期间从根解析,另一个从注入组件的应用作用域解析。 这意味着恢复后的状态没有传递到组件所使用的实例。 在客户端上将服务注册为单一实例可确保将同一实例用于状态还原和组件注入。

将 CounterTracker 服务注入组件,并将其用于递增计数器。 为了示范以下示例,服务的 CurrentCount 属性值只在预渲染时设置为 10。

Pages/Counter.razor:

@page "/counter"
@inject CounterTracker CounterTracker

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p>Rendering: @RendererInfo.Name</p>

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

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

@code {
    protected override void OnInitialized()
    {
        if (!RendererInfo.IsInteractive)
        {
            CounterTracker.CurrentCount = 10;
        }
    }

    private void IncrementCount()
    {
        CounterTracker.IncrementCount();
    }
}

要使用前面的组件来演示在 CounterTracker.CurrentCount 中保持计数 10,请导航到该组件并刷新浏览器,这会触发预呈现。 发生预呈现时,你会短暂地看到 RendererInfo.Name 显示“Static”,然后在最终呈现后显示“Server”。 计数器从 10 开始。

直接使用 PersistentComponentState 服务而不是声明性模型

作为使用属性来保存状态的声明性模型的一种替代方法,可以直接使用服务,这为复杂的状态持久性场景提供了更大的灵活性。 调用 PersistentComponentState.RegisterOnPersisting 以注册回调以在预呈现期间保留组件状态。 在组件以交互方式渲染时,会检索状态。 在初始化代码结束时进行调用,以避免在应用关闭期间出现潜在的争用条件。

以下计数器组件在预呈现期间保留计数器状态,然后检索状态以初始化组件。

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();
}

执行组件时,currentCount 仅在预呈现期间设置一次。 重新呈现组件时,会还原该值。 下面是示例输出。

注释

如果应用采用 交互式路由,并且通过内部 增强导航访问页面,则不会进行预呈现。 因此,必须为组件执行完整页面重载才能查看以下输出。 有关详细信息,请参阅 交互式路由和预呈现 部分。

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

若要保留预呈现状态,请决定使用 PersistentComponentState 服务保留什么状态。 PersistentComponentState.RegisterOnPersisting 注册回调以在预呈现期间保留组件状态。 在组件以交互方式渲染时,会检索状态。 在初始化代码结束时进行调用,以避免在应用关闭期间出现潜在的争用条件。

以下计数器组件在预呈现期间保留计数器状态,然后检索状态以初始化组件。

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++;
}

执行组件时,currentCount 仅在预呈现期间设置一次。 重新呈现组件时,会还原该值。 下面是示例输出。

注释

如果应用采用 交互式路由,并且通过内部 增强导航访问页面,则不会进行预呈现。 因此,必须为组件执行完整页面重载才能查看以下输出。 有关详细信息,请参阅 交互式路由和预呈现 部分。

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

持久性组件状态的序列化扩展性

使用 PersistentComponentStateSerializer<T> 实现自定义序列化程序。 如果没有注册的自定义序列化程序,序列化将回退到现有的 JSON 序列化。

以下示例为 int? 类型创建了一个自定义序列化程序,该程序使用自定义格式来演示序列化的可扩展性。 序列化程序使用“”CUSTOM:为整数值添加前缀,以清楚地区分它们与 JSON 序列化。

序列化程序 单独对可以为 null 和不可为 null 的类型执行,因此以下序列化程序不会对 int 类型执行,只处理可为 null 的整数类型(int?)。

以下示例中的日志记录用于演示目的,通常不会在生产应用中实现。

CustomIntSerializer.cs:

using System;
using System.Buffers;
using System.Text;
using Microsoft.AspNetCore.Components;
using Microsoft.Extensions.Logging;

namespace BlazorSample;

public class CustomIntSerializer(ILogger<CustomIntSerializer> logger) 
    : PersistentComponentStateSerializer<int?>
{
    public override void Persist(int? value, IBufferWriter<byte> writer)
    {
        string customFormat = 
            value is not null ? $"CUSTOM:{value}" : $"CUSTOM:null";

        logger.LogInformation(
            "Persisting value {Value} with custom format: {CustomFormat}", value, 
            customFormat);

        byte[] bytes = Encoding.UTF8.GetBytes(customFormat);
        writer.Write(bytes);
    }

    public override int? Restore(ReadOnlySequence<byte> data)
    {
        byte[] bytes = data.ToArray();
        string text = Encoding.UTF8.GetString(bytes);

        logger.LogInformation("Restoring value from custom format: {CustomFormat}", 
            text);

        if (text.StartsWith("CUSTOM:", StringComparison.Ordinal))
        {
            var remainingText = text.AsSpan(7);

            if (!remainingText.SequenceEqual("null"))
            {
                if (int.TryParse(remainingText, out int value))
                {
                    return value;
                }
            }
            else
            {
                return null;
            }
        }

        // Fallback to direct parsing if format is unexpected
        return int.TryParse(text, out int fallbackValue) ? fallbackValue : null;
    }
}

自定义序列化程序在应用的 Program 文件中注册:

builder.Services.AddSingleton<PersistentComponentStateSerializer<int?>, 
    CustomIntSerializer>();

该 int? 类型使用自定义序列化程序自动持久保存和还原:

[PersistentState]
public int? CurrentCount { get; set; }

使用前面的序列化程序对本文PrerenderedCounter2中所示的 PrerenderedCounter2.razor 组件()进行处理时,会记录类似如下的输出。

注释

如果应用采用 交互式路由,并且通过内部 增强导航访问页面,则不会进行预呈现。 因此,必须为组件执行完整页面重载才能查看以下输出。 有关详细信息,请参阅 交互式路由和预呈现 部分。

info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
CurrentCount set to 49
info: BlazorSample.CustomIntSerializer[0]
Persisting value 49 with custom format: CUSTOM:49
info: BlazorSample.CustomIntSerializer[0]
Restoring value from custom format: CUSTOM:49
info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
CurrentCount restored to 49

嵌入到页面和视图中的组件 (Razor Pages/MVC)

对于嵌入到 Razor Pages 或 MVC 应用的页面或视图中的组件,必须添加持久组件状态标记帮助程序,并将 <persist-component-state /> HTML 标记置于应用布局的结束 </body> 标记内。 这仅对于 Razor Pages 和 MVC 应用是必需的。 有关详细信息,请参阅 ASP.NET Core 中的持久化组件状态标记帮助器。

Pages/Shared/_Layout.cshtml:

<body>
    ...

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

交互式路由和预呈现

当 Routes 组件未定义呈现模式时,应用将使用每页/组件交互和导航。 使用每页/组件导航时,内部导航由 增强型路由 在应用变为交互式后进行处理。 此上下文中的“内部导航”意味着导航事件的 URL 目标是 Blazor 应用中的终结点。

Blazor 支持在 增强导航期间处理持久性组件状态。 增强导航期间保留的状态可由页面上的互动组件读取。

默认情况下,持久组件状态仅在最初加载到页面上时由交互式组件加载。 在组件加载后,这可以防止编辑后的网页表单数据等重要状态被覆盖,特别是在发生向同一页面的额外增强导航事件时。

如果数据是只读的且不经常更改,请选择通过在 [PersistentState] 属性上将 AllowUpdates 设置为 true 来允许在增强导航期间更新。 这对于显示缓存的数据(例如,提取成本高昂但不会经常更改)等方案非常有用,例如以下示例中的天气预报数据:

[PersistentState(AllowUpdates = true)]
public WeatherForecast[]? Forecasts { get; set; }

protected override async Task OnInitializedAsync()
{
    Forecasts ??= await ForecastService.GetForecastAsync();
}

注释

PersistentStateAttribute.AllowUpdates 不控制当线路暂停时(包括由选项卡不活动引起的自动暂停),当前属性值是否被线路状态持久化捕获。

注释

PersistentStateAttribute.AllowUpdates 不会控制当电路暂停时,当前属性值是否由 电路状态持久化 保存。

若要在预呈现期间跳过还原状态,请设置为RestoreBehaviorSkipInitialValue:

[PersistentState(RestoreBehavior = RestoreBehavior.SkipInitialValue)]
public string NoPrerenderedData { get; set; }

若要在重新连接期间跳过还原状态,请设置为 RestoreBehaviorSkipLastSnapshot. 这对于在重新连接后确保新数据非常有用:

[PersistentState(RestoreBehavior = RestoreBehavior.SkipLastSnapshot)]
public int CounterNotRestoredOnReconnect { get; set; }

调用 PersistentComponentState.RegisterOnRestoring 以注册回调,来以命令式控制状态的还原方式,类似于 PersistentComponentState.RegisterOnPersisting 提供对状态持久化方式的完全控制。

PersistentComponentState 服务仅适用于初始页面加载,不适用于内部增强的页面导航事件。

如果应用使用持久性组件状态对页面执行完整(非增强)导航,则应用在变为交互式时可以使用持久状态。

如果已建立交互式电路,并且对利用持久性组件状态的页面执行增强导航,则现有电路中不提供 状态,供组件使用。 内部页面请求没有预渲染,并且 PersistentComponentState 服务不了解发生了增强导航。 没有向已在现有线路上运行的组件提供状态更新的机制。 原因是,Blazor 仅支持在运行时初始化时将状态从服务器传递到客户端,而不是在运行时启动之后。

在PersistentComponentState中,介绍了禁用增强导航。虽然这可能降低性能,但也能避免内部页面请求中与Blazor加载状态有关的问题。 或者,将应用更新为 .NET 10 或更高版本,其中Blazor支持在增强导航期间处理永久性组件状态。