Add a Blazor WebWorker article to client-side development coverage

[ilonatommy]

Similar as #36168 but for Blazor.

1. I think we can keep the name "Blazor with .Net on Web Worker", it will be symmetric to ".Net on Web Worker" that we used to the sample with React frontend.
2. Moving https://github.com/ilonatommy/blazorWithDotnetOnWebWorker to samples, next to https://github.com/dotnet/blazor-samples/tree/main/10.0/DotNetOnWebWorkers.
3. I am still waiting for @danroth27's opinion but for now, let's assume we'll place the article in Blazor JSInterop section, next to https://learn.microsoft.com/en-us/aspnet/core/blazor/javascript-interoperability. The suggestion I got is to put it next to https://learn.microsoft.com/en-us/aspnet/core/blazor/webassembly-native-dependencies and https://learn.microsoft.com/en-us/aspnet/core/blazor/webassembly-lazy-load-assemblies. One level higher than JSInterop.
4. We would like to cross-link between both .NET on Web Worker articles.
5. The contents of the article will be posted in form of a comment under this issue.

Contributes to dotnet/runtime#95452.

[guardrex]

@ilonatommy ... I'll take care of placing that sample app. I'll ping you on the PR. I should reach that task fairly soon ... within a day or two.

[ilonatommy]

Web workers on Blazor

Modern Blazor WebAssembly apps often handle CPU-intensive work alongside rich UI updates. Tasks like image processing, document parsing, or data crunching can easily freeze the browser's main thread. Web Workers let you push that work to a background thread. Combined with the .NET WebAssembly runtime, you can keep writing C# while the UI stays responsive.

The guidance in this article mirrors the concepts from the React-focused .NET on Web Workers walkthrough, but adapts every step to a Blazor frontend. It highlights the same QR-code generation scenario implemented in this repository.

To read about Web Workers with React, read this article.

Sample app

Explore a complete working implementation in the Blazor samples GitHub repository. The sample is available for .NET 10 or later and named BlazorWithDotNetOnWebWorkers.

Prerequisites and setup

Before diving into the implementation, ensure the necessary tools are installed. The .NET SDK 8.0 or later is required.

Create the Blazor WebAssembly project

To start from scratch, create a new Blazor WASM app:

dotnet new blazorwasm -n WebWorkersOnBlazor
cd WebWorkersOnBlazor

In this article we are using QRCoder package to symulate heavy computations:

dotnet add package QRCoder

Add <AllowUnsafeBlocks>true</AllowUnsafeBlocks> to your project properties. AllowUnsafeBlocks is required whenever you use JSImport or JSExport in WebAssembly projects.

Add the Worker Code

Create Workers/QRGenerator.razor.cs. This file exposes .NET code to JavaScript by using JSExport. Create a matching .razor file that is an empty stub so that the build packs the worker script alongside the component assets.

using System;
using System.Runtime.InteropServices.JavaScript;
using System.Runtime.Versioning;
using QRCoder;

[SupportedOSPlatform("browser")]
public partial class QRGenerator
{
    private static readonly int MaxQrSize = 20;

    [JSExport]
    internal static byte[] Generate(string text, int qrSize)
    {
        if (qrSize >= MaxQrSize)
        {
            throw new Exception($"QR code size must be less than {MaxQrSize}.");
        }

        var generator = new QRCodeGenerator();
        QRCodeData data = generator.CreateQrCode(text, QRCodeGenerator.ECCLevel.Q);
        var qrCode = new BitmapByteQRCode(data);
        return qrCode.GetGraphic(qrSize);
    }
}

Add Workers/QRGenerator.razor.js file. This script boots the .NET runtime in the worker, then listens for messages from the main thread. postMessage will be used to send either a result or an error payload.

import { dotnet } from '../_framework/dotnet.js';

let assemblyExports;
let startupError;

try {
  const { getAssemblyExports, getConfig } = await dotnet.create();
  const config = getConfig();
  assemblyExports = await getAssemblyExports(config.mainAssemblyName);
} catch (err) {
  startupError = err.message;
}

self.addEventListener('message', async e => {
  try {
    if (!assemblyExports) {
      throw new Error(startupError || 'worker exports not loaded');
    }

    let result;
    switch (e.data.command) {
      case 'generateQR':
        result = assemblyExports.QRGenerator.Generate(e.data.text, e.data.size);
        break;
      default:
        throw new Error(`Unknown command: ${e.data.command}`);
    }

    self.postMessage({ command: 'response', requestId: e.data.requestId, result });
  } catch (err) {
    self.postMessage({ command: 'response', requestId: e.data.requestId, error: err.message });
  }
});

Bridge the worker to the Blazor UI

Create Clients/Client.razor.js that manages the worker instance and exposes helper functions to Blazor:

const pendingRequests = {};
let pendingRequestId = 0;

const dotnetWorker = new Worker('./Workers/QRGenerator.razor.js', { type: 'module' });

dotnetWorker.addEventListener('message', e => {
  switch (e.data.command) {
    case 'response':
      const request = pendingRequests[e.data.requestId];
      delete pendingRequests[e.data.requestId];
      if (e.data.error) {
        request.reject(new Error(e.data.error));
      }
      request.resolve(e.data.result);
      break;
    default:
      console.log('Worker said:', e.data);
  }
});

function sendRequestToWorker(request) {
  pendingRequestId++;
  const promise = new Promise((resolve, reject) => {
    pendingRequests[pendingRequestId] = { resolve, reject };
  });

  dotnetWorker.postMessage({ ...request, requestId: pendingRequestId });
  return promise;
}

export async function generateQR(text, size) {
  const response = await sendRequestToWorker({ command: 'generateQR', text, size });
  const blob = new Blob([response], { type: 'image/png' });
  return URL.createObjectURL(blob);
}

Similarly as the worker, Client needs creation of a matching .razor file with an empty stub to assure that the JS file is considered a part of the component.
In the Clients/Client.razor.cs expose the JavaScript module to Blazor components through JSImport:

using System.Runtime.InteropServices.JavaScript;
using System.Runtime.Versioning;

[SupportedOSPlatform("browser")]
public partial class Client
{
    private static bool _workerStarted;

    public static async Task InitClient()
    {
        if (_workerStarted)
        {
            return;
        }

        _workerStarted = true;
        await JSHost.ImportAsync(moduleName: nameof(Client), moduleUrl: "../Clients/Client.razor.js");
    }

    [JSImport("generateQR", nameof(Client))]
    public static partial Task<string> GenerateQR(string text, int size);
}

InitClient ensures the worker JS module is only loaded once per browser session.

Use the Setup

You can use e.g. the home page (Pages/Home.razor) to demonstrate the flow:

@page "/"
@namespace Pages

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

<div class="input-container">
    <div class="form-group">
        <label for="textInput">Generate a QR from text:</label>
        <input type="text" class="form-control" id="textInput" @bind="text" />
    </div>

    <div class="form-group">
        <label for="numberInput">Set size of QR (in pixels):</label>
        <input type="number" class="form-control" id="numberInput" @bind="size" />
    </div>
    <div class="form-group">
        <button class="btn btn-primary" @onclick="GenerateQR">Generate QR</button>
    </div>
    @if (!string.IsNullOrWhiteSpace(ImageUrl))
    {
        <div class="form-group">
            <img class="image" src="@ImageUrl" id="qrImage" alt="Image" />
        </div>
    }
</div>

The corresponding code-behind in Home.razor.cs wires everything together:

using Microsoft.AspNetCore.Components;
using System.Runtime.Versioning;

namespace Pages;

[SupportedOSPlatform("browser")]
public partial class Home : ComponentBase
{
    private string ImageUrl = string.Empty;
    private string text = "Type text to generate QR";
    private int size = 5;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        await Client.InitClient();
    }

    private async Task GenerateQR()
    {
        try
        {
            ImageUrl = await Client.GenerateQR(text, size);
        }
        catch
        {
            ImageUrl = string.Empty;
        }
        await InvokeAsync(StateHasChanged);
    }
}

OnAfterRenderAsync guarantees that the JavaScript module is loaded before the user clicks the button, while the GenerateQR handler makes a single asynchronous worker request.

Next steps

• Swap the QR-code sample for your own CPU-intensive domain logic.
• Move long-running workflows into dedicated worker instances per feature area.
• Explore shared array buffers or Atomics when you need higher-throughput synchronization between Blazor and workers.

See the sample app for a demonstration of the preceding concepts.