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 回傳一個不完整且未使用 CancellationToken 的 Task，並且元件在 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;
}

在前述範例中:

• 計時器是在不依賴 Blazor 的情況下，在 _ = Task.Run(Timer.Start) 的同步上下文之外啟動的。
• 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 時，通常稱為「即發即忘」模式，因為該方法會被觸發 (啟動) 且該方法的結果會被遺忘 (丟棄)。 如果作業失敗，您可能會希望該元件將失敗視為元件生命週期例外狀況，以實現下列任一目標：

• 例如，將元件置於錯誤狀態，以觸發錯誤界限。
• 如果沒有錯誤界限，則終止該線路。
• 啟動與生命週期例外狀況一樣的日誌記錄。

在下列範例中，使用者選取 [傳送報告] 按鈕以觸發傳送報告的背景方法 ReportSender.SendAsync。 在大部分情況下，元件會等候非同步呼叫的 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 達到二的值時擲出例外：

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 元件和元件階層中其餘元件的互動功能，請在 HeadOutlet 元件中啟用 Routes 和 App 元件實例的互動式轉譯（Components/App.razor）。 下列範例採用互動式伺服器 (InteractiveServer) 轉譯模式：

<HeadOutlet @rendermode="InteractiveServer" />

...

<Routes @rendermode="InteractiveServer" />

如果您此時執行應用程式，當計數達到二時，就會拋出例外。 不過，UI 不會變更。 錯誤界限不會顯示錯誤內容。

若要將例外狀況從計時器服務分派回到 Notifications 元件，請對該元件進行下列變更：

• 在 try-catch 陳述式中啟動計時器。 在 catch 區塊的 try-catch 子句中，透過將 Exception 傳遞給 DispatchExceptionAsync 並等待結果來將例外狀況分派回到該元件。
• 在 StartTimer 方法中，在 Action 的 Task.Run 委託中啟動非同步計時器服務，並刻意捨棄傳回的 Task。

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

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

當計時器服務執行並達到 2 的計數時，例外狀況會分派至 Razor 元件，進而觸發錯誤界限以顯示 <ErrorBoundary> 元件中 MainLayout 的錯誤內容：

Oh, dear! Oh, my! - George Takei