[Blazor] Trigger state persistence from the server

[javiercn]

• Our current APIs need to be triggered from the browser.
• There are some "scheduling" issues if we try to invoke the browser APIs from the server.

Ideally, we want to provide a RequestCircuitPause API on the Circuit that the CircuitHandler instances receive that signals the browser that it needs to start pausing the circuit.

We want the client to always be involved and drive the process in graceful pause scenarios as it needs to be able to modify the UI as needed for a proper experience. Like blocking interaction by displaying a dialog (similar to the reconnect dialog one).

[javiercn]

Some more data.

Did an experiment and got this to work with the existing APIs and a small set of changes.

The main change is that I had to define a wrapper around pauseCircuit as the JS interop call must return synchronously or otherwise it fails when we try to send the response as pauseCircuit will close the connection after completing.

The other challenge is that we need to block the shutdown during appLifetime.ApplicationStopping until all the client circuits have completed the pause operation. We can't use a hosted service because connections are closed at that point already. Blocking with a TCS is the only way to perform async work within ApplicationStopping that gives the client time to request the pause.

---

Blazor Server Circuit Pause & Resume on Server Shutdown

This guide explains how to implement server-triggered circuit pause in a Blazor Web App (.NET 10+). This allows you to gracefully pause client circuits when the server is shutting down, preserving client state for seamless reconnection.

Prerequisites

• .NET 10 or later - The Blazor.pauseCircuit() and Blazor.resumeCircuit() JavaScript APIs are only available in .NET 10+
• Blazor Web App with InteractiveServer render mode

Overview

When a Blazor Server application shuts down (e.g., during deployment), connected clients lose their SignalR connection. This implementation:

1. Detects shutdown before the server closes connections
2. Triggers pause on all connected circuits via JavaScript interop
3. Preserves state using [PersistentState] attribute on component properties

---

Implementation

File Structure

Shutdown/
├── CircuitShutdownService.cs   # Singleton - coordinates shutdown
├── ShutdownCircuitHandler.cs   # Scoped - one per circuit
└── ShutdownCircuitOptions.cs   # Configuration options

ShutdownCircuitOptions.cs

namespace PauseResumeOnShutdown.Shutdown;

public class ShutdownCircuitOptions
{
    public TimeSpan ShutdownTimeout { get; set; } = TimeSpan.FromSeconds(10);
}

CircuitShutdownService.cs

using System.Collections.Concurrent;
using Microsoft.Extensions.Options;

namespace PauseResumeOnShutdown.Shutdown;

public class CircuitShutdownService
{
    private readonly ConcurrentDictionary<string, ShutdownCircuitHandler> _handlers = new();
    private readonly ShutdownCircuitOptions _options;
    private bool _isShuttingDown;
    private TaskCompletionSource _shutdownTcs = new();

    public CircuitShutdownService(IHostApplicationLifetime appLifetime, IOptions<ShutdownCircuitOptions> options)
    {
        _options = options.Value;
        appLifetime.ApplicationStopping.Register(OnApplicationStopping);
    }

    private void OnApplicationStopping()
    {
        _isShuttingDown = true;

        if (_handlers.IsEmpty)
        {
            return;
        }

        foreach (var handler in _handlers.Values)
        {
            handler.Pause();
        }

        _shutdownTcs.Task.Wait(_options.ShutdownTimeout);
    }

    public void Register(string circuitId, ShutdownCircuitHandler handler)
    {
        _handlers.TryAdd(circuitId, handler);
    }

    public void Unregister(string circuitId)
    {
        _handlers.TryRemove(circuitId, out _);
        if (_isShuttingDown && _handlers.IsEmpty)
        {
            _shutdownTcs.TrySetResult();
        }
    }
}

ShutdownCircuitHandler.cs

using Microsoft.AspNetCore.Components.Server.Circuits;
using Microsoft.JSInterop;

namespace PauseResumeOnShutdown.Shutdown;

public class ShutdownCircuitHandler(
    CircuitShutdownService shutdownService,
    IJSRuntime jsRuntime) : CircuitHandler
{
    public override Task OnConnectionUpAsync(Circuit circuit, CancellationToken cancellationToken)
    {
        shutdownService.Register(circuit.Id, this);
        return Task.CompletedTask;
    }

    public override Task OnConnectionDownAsync(Circuit circuit, CancellationToken cancellationToken)
    {
        shutdownService.Unregister(circuit.Id);
        return Task.CompletedTask;
    }

    public void Pause()
    {
        _ = PauseCore();
    }

    private async Task PauseCore()
    {
        try
        {
            await jsRuntime.InvokeVoidAsync("remotePause");
        }
        catch
        {
        }
    }
}

Program.cs

using Microsoft.AspNetCore.Components.Server.Circuits;
using Microsoft.Extensions.DependencyInjection.Extensions;
using PauseResumeOnShutdown.Components;
using PauseResumeOnShutdown.Shutdown;

var builder = WebApplication.CreateBuilder(args);

// Increase shutdown timeout to allow time for pause operations
builder.Host.ConfigureHostOptions(options =>
    options.ShutdownTimeout = TimeSpan.FromSeconds(30));

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// Register CircuitShutdownService as a singleton
builder.Services.AddSingleton<CircuitShutdownService>();

// Register ShutdownCircuitHandler as a scoped CircuitHandler
builder.Services.TryAddEnumerable(
    ServiceDescriptor.Scoped<CircuitHandler, ShutdownCircuitHandler>());

var app = builder.Build();

// ... rest of pipeline

App.razor (JavaScript)

Add this script after the Blazor script reference:

<script src="@Assets["_framework/blazor.web.js"]"></script>
<script>
    // Called from the server to trigger pause - returns immediately to avoid
    // "Cannot send data" error when Blazor tries to send the response back
    window.remotePause = function () {
        Blazor.pauseCircuit();
    };
</script>

Critical: The remotePause function must NOT be async and must NOT return a value. If it returns a Promise, Blazor will try to send the result back after the connection closes, causing an error.

Counter.razor (State Persistence)

Use [PersistentState] attribute to persist component state across pause/resume:

@page "/counter"
@rendermode InteractiveServer

<PageTitle>Counter</PageTitle>

<h1>Counter</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; }

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

---

How It Works

Shutdown Flow

sequenceDiagram
    participant Orchestrator as Orchestrator/Environment
    participant Host as .NET Host
    participant Service as CircuitShutdownService
    participant Handler as ShutdownCircuitHandler
    participant JS as Browser (JS)
    participant Hub as ComponentHub
    participant Registry as CircuitRegistry
    participant Persistence as CircuitPersistenceManager

    Orchestrator->>Host: SIGTERM / Stop Signal
    Host->>Service: ApplicationStopping fires
    Service->>Service: _isShuttingDown = true
    
    loop For each circuit
        Service->>Handler: Pause()
        Handler->>JS: InvokeVoidAsync("remotePause")
        JS->>JS: Blazor.pauseCircuit()
        JS->>Hub: PauseCircuit() [SignalR]
        Hub->>Registry: PauseCircuitAsync()
        Registry->>Persistence: PauseCircuitAsync()
        Persistence->>Persistence: Collect [PersistentState] values
        Persistence->>Persistence: Serialize root components
        Persistence->>JS: SendPersistedStateToClient()
        JS->>JS: Store state locally
        JS->>JS: Disconnect SignalR
    end
    
    Note over Handler,Service: OnConnectionDownAsync triggers
    Handler->>Service: Unregister(circuitId)
    Service->>Service: _shutdownTcs.TrySetResult()
    Service-->>Host: OnApplicationStopping returns
    Host->>Host: Server.StopAsync()

Loading

Configuration

Shutdown Timeout (Options)

builder.Services.Configure<ShutdownCircuitOptions>(options =>
    options.ShutdownTimeout = TimeSpan.FromSeconds(15));

Host Shutdown Timeout

builder.Host.ConfigureHostOptions(options =>
    options.ShutdownTimeout = TimeSpan.FromSeconds(60));

[tombrewer-onwave]

We're trying out something close with a few variations that might be useful to others:

Hybrid approach: SSE broadcast + TCS-based waiting

SSE instead of per-circuit JS interop - We broadcast shutdown notifications via Server-Sent Events (EventSource). The client listens and calls Blazor.pauseCircuit() itself, avoiding the synchronous JS wrapper requirement (since there's no response to send back).

SIGTERM interception before ApplicationStopping - On Linux containers, we intercept SIGTERM with context.Cancel = true and broadcast before the host starts closing connections. This gives clients more time to pause.

TCS-based waiting (per your pattern) - We've borrowed the active circuits tracking (above) via a CircuitHandler to wait until all have closed (or timeout), rather than a fixed delay (which is what we had) as it's obviously more efficient when circuits close quickly and probably more reliable.

Client-side token management - localStorage with timestamp-based expiry, exponential backoff on resumeCircuit() retries (handles "Circuit host not initialized" during early reconnection), graceful fallback to page reload.

Happy to share more details on any of these if helpful for the platform improvement discussion.

[tombrewer-onwave]

One note I should add (for customers like myself stumbling across this) is that SSE doesn't seem to work through Azure Front Door (but I believe can through Azure App Gateway), so anyone using that as a client call-back mechanism (in this case the notification to pause and persist circuit state) would need to use a different proxy or solution (like piggybacking the Signal-R connection) in front of their app. Ideally we'll get this native and integrated into .NET soon anyway so we won't need a separate channel or mechanism.

[tombrewer-onwave]

We're testing replacing the SSE solution with JS interop through the existing Blazor circuit WebSocket — a singleton ShutdownCircuitNotifier tracks each circuit's IJSRuntime and broadcasts onShutdown() to all circuits in parallel on SIGTERM. So no new connections (will work through Azure Front Door) with the TCS-based circuit drain waiting is still in place.