ASP.NET Core Blazor 同步上下文

Blazor 使用同步上下文 (SynchronizationContext) 来强制执行单个逻辑线程。 组件的生命周期方法和 Blazor 引发的事件回调都在此同步上下文上执行。

Blazor 的服务器端同步上下文尝试模拟单线程环境，使其与浏览器（单线程）中的 WebAssembly 模型密切匹配。 此仿真的范围仅限于单个线路，这意味着两个不同的线路可以并行运行。 在一条线路中的任意给定时间点，工作只在一个线程上执行，这会造成单个逻辑线程的印象。 同一线路中不会同时执行两个操作。

单个逻辑执行线程并不意味着单个异步控制流。 组件在等待未完成的 Task 时随时可重入。 生命周期方法 或 组件处置方法 可能在等待 Task 完成后恢复异步控制流之前被调用。 因此，组件必须确保它在等待可能未完成的 Task 之前处于有效状态。 具体而言，组件必须确保它在 OnInitializedAsync 或 OnParametersSetAsync 返回时处于渲染的有效状态。 如果其中任一方法返回不完整的 Task，则必须确保同步完成的方法的一部分使组件处于有效的呈现状态。

可重入组件的另一个含义是，某方法不能推迟 Task，除非该方法通过将其传递给 ComponentBase.InvokeAsync 返回。 调用 ComponentBase.InvokeAsync 只能延迟 Task，直到达到下一个 await 运算符。

组件可能实现 IDisposable 或 IAsyncDisposable，以使用组件被处置时取消的 CancellationTokenSource 中的 CancellationToken 调用异步方法。 但是，这确实取决于方案。 由组件作者决定这是否是正确的行为。 例如，如果实现在选择保存按钮时将某些本地数据保存到数据库的 SaveButton 组件，那么如果用户选择该按钮并快速导航到另一个页面，则组件作者可能确实打算放弃更改，这会在异步保存完成之前释放组件。

一次性组件在等待未收到组件 CancellationToken 的任何 Task 后，可以检查处置情况。 未完成的 Task 也可能阻止垃圾回收已处置的组件。

ComponentBase 忽略 Task 取消引起的异常（更确切地说，如果取消等待的 Task，则 忽略所有 异常），因此组件方法无需处理 TaskCanceledException 和 OperationCanceledException。

ComponentBase 不能遵循上述准则，因为它不将构成派生组件的有效状态概念化，并且它本身不实现 IDisposable 或 IAsyncDisposable。 如果 OnInitializedAsync 返回一个不完整的 Task，且该 Task 未使用 CancellationToken，并且组件在 Task 完成之前被释放，那么 ComponentBase 仍会调用 OnParametersSet 并等待 OnParametersSetAsync。 如果一次性组件不使用 CancellationToken，OnParametersSet 和 OnParametersSetAsync 应检查组件是否已处置。

避免阻止线程的调用

通常，不要在组件中调用以下方法。 以下方法阻止执行线程，进而阻止应用继续工作，直到基础 Task 完成：

• Result
• Wait
• WaitAny
• WaitAll
• Sleep
• GetResult

注意

使用此部分中所述的线程阻止方法的 Blazor 文档示例只是使用方法进行演示，而不是用作建议编码指导。 例如，一些组件代码演示通过调用 Thread.Sleep 来模拟长时间运行的进程。

在外部调用组件方法以更新状态

如果组件必须根据外部事件（如计时器或其他通知）进行更新，请使用 InvokeAsync 方法，它将代码执行调度到 Blazor 的同步上下文。 例如，请考虑以下通告程序服务，它可向任何侦听组件通知更新的状态。 可以从应用中的任何位置调用 Update 方法。

TimerService.cs:

namespace BlazorSample;

public class TimerService(NotifierService notifier, 
    ILogger<TimerService> logger) : IDisposable
{
    private int elapsedCount;
    private readonly static TimeSpan heartbeatTickRate = TimeSpan.FromSeconds(5);
    private readonly ILogger<TimerService> logger = logger;
    private readonly NotifierService notifier = notifier;
    private PeriodicTimer? timer;

    public async Task Start()
    {
        if (timer is null)
        {
            timer = new(heartbeatTickRate);
            logger.LogInformation("Started");

            using (timer)
            {
                while (await timer.WaitForNextTickAsync())
                {
                    elapsedCount += 1;
                    await notifier.Update("elapsedCount", elapsedCount);
                    logger.LogInformation("ElapsedCount {Count}", elapsedCount);
                }
            }
        }
    }

    public void Dispose()
    {
        timer?.Dispose();

        // The following prevents derived types that introduce a
        // finalizer from needing to re-implement IDisposable.
        GC.SuppressFinalize(this);
    }
}

NotifierService.cs:

namespace BlazorSample;

public class NotifierService
{
    public async Task Update(string key, int value)
    {
        if (Notify != null)
        {
            await Notify.Invoke(key, value);
        }
    }

    public event Func<string, int, Task>? Notify;
}

注册服务：

• 对于客户端开发，请在客户端 Program 文件中将服务注册为单一实例：

  builder.Services.AddSingleton<NotifierService>();
  builder.Services.AddSingleton<TimerService>();
  

• 对于服务器端开发，请在服务器 Program 文件中将服务注册为限定范围：

  builder.Services.AddScoped<NotifierService>();
  builder.Services.AddScoped<TimerService>();
  

使用 NotifierService 更新组件。

Notifications.razor:

@page "/notifications"
@implements IDisposable
@inject NotifierService Notifier
@inject TimerService Timer

<PageTitle>Notifications</PageTitle>

<h1>Notifications Example</h1>

<h2>Timer Service</h2>

<button @onclick="StartTimer">Start Timer</button>

<h2>Notifications</h2>

<p>
    Status:
    @if (lastNotification.key is not null)
    {
        <span>@lastNotification.key = @lastNotification.value</span>
    }
    else
    {
        <span>Awaiting notification</span>
    }
</p>

@code {
    private (string key, int value) lastNotification;

    protected override void OnInitialized() => Notifier.Notify += OnNotify;

    public async Task OnNotify(string key, int value)
    {
        await InvokeAsync(() =>
        {
            lastNotification = (key, value);
            StateHasChanged();
        });
    }

    private void StartTimer() => _ = Task.Run(Timer.Start);

    public void Dispose() => Notifier.Notify -= OnNotify;
}

在上面的示例中：

• 计时器是使用 _ = Task.Run(Timer.Start) 在 Blazor 的外部启动的。
• NotifierService 会调用该组件的 OnNotify 方法。 InvokeAsync 用于切换到正确的上下文，并将呈现器排入队列。 有关详细信息，请参阅 ASP.NET Core Razor 组件呈现。
• 组件实现 IDisposable。 OnNotify 委托在 Dispose 方法中取消订阅，在释放组件时，框架会调用此方法。 有关详细信息，请参阅 ASP.NET Core Razor 组件处置。

重要

如果组件 Razor 定义从后台线程触发的事件，则可能需要该组件在注册处理程序时捕获和还原执行上下文 (ExecutionContext)。 有关更多信息，请参阅调用 InvokeAsync(StateHasChanged) 会导致页面降级至默认文化 (dotnet/aspnetcore #28521)。

要将捕获的异常从后台 TimerService 调度到组件，以将异常视为正常的生命周期事件异常，请参阅在 Razor 组件生命周期以外处理捕获的异常部分。

在 Razor 组件的生命周期外处理捕获的异常

在 ComponentBase.DispatchExceptionAsync 组件中使用 Razor 来处理在组件的生命周期调用堆栈外部引发的异常。 这允许组件的代码将异常视为生命周期方法异常。 此后，Blazor 的错误处理机制（如错误边界）可以处理异常。

注意

ComponentBase.DispatchExceptionAsync 用于继承自 Razor 的 .razor 组件文件 (ComponentBase)。 创建实现 implement IComponent directly 的组件时，请使用 RenderHandle.DispatchExceptionAsync。

若要处理在 Razor 组件生命周期之外捕获的异常，请将异常传递给 DispatchExceptionAsync，然后等待结果：

try
{
    ...
}
catch (Exception ex)
{
    await DispatchExceptionAsync(ex);
}

上述方法的一个常见场景是某个组件启动了一个异步操作但不等待 Task，通常称为“发后即忘”模式，因为方法被触发（启动），而方法的结果被遗忘（丢弃）。 如果操作失败，你可能希望组件将失败视为组件生命周期异常，出于以下任何目标：

• 例如，将组件置于出错状态，以触发错误边界。
• 如果没有错误边界，则终止线路。
• 触发针对生命周期异常发生的相同日志记录。

在以下示例中，用户选择“发送报表”按钮，以触发发送报表的后台方法 。 在大多数情况下，组件会等待异步调用的 Task，并更新 UI 以指示操作已完成。 在以下示例中，SendReport 方法不会等待 Task，也不会向用户报告结果。 由于组件在 SendReport 中有意舍弃 Task，任何异步故障都发生在正常生命周期调用堆栈之外，因此不会被 Blazor 看到：

<button @onclick="SendReport">Send report</button>

@code {
    private void SendReport()
    {
        _ = ReportSender.SendAsync();
    }
}

若要处理生命周期方法异常等故障，请使用 DispatchExceptionAsync 将异常显式调度回组件，如以下示例所示：

<button @onclick="SendReport">Send report</button>

@code {
    private void SendReport()
    {
        _ = SendReportAsync();
    }

    private async Task SendReportAsync()
    {
        try
        {
            await ReportSender.SendAsync();
        }
        catch (Exception ex)
        {
            await DispatchExceptionAsync(ex);
        }
    }
}

替代方法利用 Task.Run：

private void SendReport()
{
    _ = Task.Run(async () =>
    {
        try
        {
            await ReportSender.SendAsync();
        }
        catch (Exception ex)
        {
            await DispatchExceptionAsync(ex);
        }
    });
}

若要进行有效演示，请实现从外部调用组件方法以更新状态中的计时器通知示例。 在 Blazor 应用中，从计时器通知示例中添加以下文件，并在 Program 文件中注册服务，如以下部分所述：

• TimerService.cs
• NotifierService.cs
• Notifications.razor

该示例使用 Razor 组件生命周期之外的计时器，其中未处理的异常通常不会由 Blazor 的错误处理机制（如错误边界）处理。

首先，更改 TimerService.cs 中的代码，以在组件的生命周期之外创建人工异常。 在 while 的 TimerService.cs 循环中，当 elapsedCount 达到 2 的值时引发异常：

if (elapsedCount == 2)
{
    throw new Exception("I threw an exception! Somebody help me!");
}

在应用的主布局中放置错误边界。 将 <article>...</article> 标记替换为以下标记。

在 MainLayout.razor中：

<article class="content px-4">
    <ErrorBoundary>
        <ChildContent>
            @Body
        </ChildContent>
        <ErrorContent>
            <p class="alert alert-danger" role="alert">
                Oh, dear! Oh, my! - George Takei
            </p>
        </ErrorContent>
    </ErrorBoundary>
</article>

在Blazor Web App中，当错误边界仅应用于静态MainLayout组件时，该边界仅在静态服务器端渲染（SSR）阶段处于活动状态。 边界不会因为组件层次结构的下一个组件是交互式的而激活。 若要为组件层次结构后面的 MainLayout 组件和其余组件启用交互性，请为 App 组件（Components/App.razor）中的 HeadOutlet 和 Routes 组件实例启用交互式呈现。 以下示例采用交互式服务器（InteractiveServer）呈现模式：

<HeadOutlet @rendermode="InteractiveServer" />

...

<Routes @rendermode="InteractiveServer" />

如果此时运行应用，当经过的计数达到 2 的值时，将引发异常。 但是，UI 不会更改。 错误边界不显示错误内容。

为了将计时器服务中的异常调度回 Notifications 组件，对组件进行了以下更改：

• 在 try-catch 语句中启动计时器。 在 catch 块的 try-catch 子句中，通过将 Exception 传给 DispatchExceptionAsync 并等待结果，将异常传递回组件。
• 在 StartTimer 方法中，在 Task.Run 的 Action 委托中启动异步计时器服务，并故意放弃返回的 Task。

Notifications 组件 (Notifications.razor) 的 StartTimer 方法：

private void StartTimer()
{
    _ = Task.Run(async () =>
    {
        try
        {
            await Timer.Start();
        }
        catch (Exception ex)
        {
            await DispatchExceptionAsync(ex);
        }
    });
}

当计时器服务执行并达到两次计数时，异常会被传递到 Razor 组件，然后触发错误边界，在 <ErrorBoundary> 组件中显示 MainLayout 的错误内容。

Oh, dear! Oh, my! - George Takei