🚀 Running Background Jobs in Blazor WASM with WJb (No Backend Required)

     // Report progress to the engine
        context.ReportProgress((i + 1) * 100 / total);
        
        // Check for cancellation
        if (context.IsCancellationRequested)
        {
            context.Cancel("User aborted export.");
            return;
        }
    }

    context.Complete($"Exported {total} records to {config.Format}.");
}

private async Task<List<DataRecord>> FetchDataAsync(string sourceId)
{
    // Fetch logic here
    return new List<DataRecord>();
}

private Task ProcessRecordAsync(DataRecord record)
{
    // Processing logic here
    return Task.CompletedTask;
}

}

public record ExportConfiguration(string SourceId, string Format); public record DataRecord(string Id, string Value);

#### 2. Register the Engine

Configure WJb in the dependency injection container during application startup.

```csharp
// Program.cs
using WJb.Core;

var builder = WebApplication.CreateBuilder(args);

// Register WJb services with default configuration
builder.Services.AddWjbEngine(options =>
{
    options.MaxConcurrency = 4;
    options.DefaultRetryCount = 3;
});

await builder.Build().RunAsync();

3. Orchestrate Jobs in the UI

Inject the scheduler into your component to manage job lifecycle. Use event subscriptions to keep the UI synchronized with job state changes.

@page "/export-dashboard"
@using WJb.Core
@using WJb.Models
@inject IJobScheduler Scheduler
@implements IDisposable

<div class="dashboard">
    <button @onclick="StartExport" disabled="@(Scheduler.IsBusy)">
        Start Export
    </button>

    <table class="job-table">
        <thead>
            <tr>
                <th>ID</th>
                <th>Status</th>
                <th>Progress</th>
                <th>Message</th>
                <th>Actions</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var entry in ActiveJobs)
            {
                <tr>
                    <td>@entry.JobId</td>
                    <td>
                        <span class="badge @GetStatusClass(entry.State.Status)">
                            @entry.State.Status
                        </span>
                    </td>
                    <td>
                        <div class="progress-bar" style="width: @entry.State.Progress%">
                            @entry.State.Progress%
                        </div>
                    </td>
                    <td>@entry.State.Message</td>
                    <td>
                        @if (entry.State.Status is JobStatus.Running or JobStatus.Queued)
                        {
                            <button @onclick="() => AbortJob(entry.JobId)">Abort</button>
                        }
                        else if (entry.State.Status is JobStatus.Failed or JobStatus.Cancelled)
                        {
                            <button @onclick="() => RequeueJob(entry.JobId)">Retry</button>
                        }
                    </td>
                </tr>
            }
        </tbody>
    </table>
</div>

@code {
    private List<JobEntry> ActiveJobs = new();

    protected override void OnInitialized()
    {
        // Subscribe to state changes for real-time updates
        Scheduler.OnStateChange += HandleStateChange;
        ActiveJobs = Scheduler.ListAll().ToList();
    }

    private async Task StartExport()
    {
        var config = new ExportConfiguration(SourceId: "db-01", Format: "CSV");
        await Scheduler.Schedule<DataExportTask, ExportConfiguration>(config);
    }

    private void AbortJob(string jobId) => Scheduler.Abort(jobId);
    private void RequeueJob(string jobId) => Scheduler.Requeue(jobId);

    private void HandleStateChange()
    {
        // Ensure UI updates occur on the synchronization context
        InvokeAsync(() =>
        {
            ActiveJobs = Scheduler.ListAll().ToList();
            StateHasChanged();
        });
    }

    private string GetStatusClass(JobStatus status) => status switch
    {
        JobStatus.Running => "badge-info",
        JobStatus.Completed => "badge-success",
        JobStatus.Failed => "badge-danger",
        JobStatus.Cancelled => "badge-warning",
        _ => "badge-secondary"
    };

    public void Dispose()
    {
        // Prevent memory leaks by unsubscribing
        Scheduler.OnStateChange -= HandleStateChange;
    }
}

Architecture Decisions

• Generic Scheduling: Using Schedule<TaskType, PayloadType> enforces type safety at compile time, preventing payload mismatches and ensuring the engine knows exactly how to serialize and deserialize job data.
• Context-Based Progress: The IJobContext interface allows tasks to report progress and check cancellation without coupling to the UI or scheduler implementation. This keeps task logic pure and testable.
• Event-Driven UI: Subscribing to OnStateChange avoids polling and ensures the UI reflects the current state immediately. Wrapping updates in InvokeAsync guarantees thread safety in Blazor's rendering model.
• Explicit Disposal: Implementing IDisposable and unsubscribing from events prevents memory leaks, which is critical in long-running single-page applications.

Pitfall Guide

Even with a robust engine like WJb, client-side job orchestration introduces unique challenges. The following pitfalls are common in production environments and include actionable fixes.

1. Main Thread Blocking

   • Explanation: Blazor WASM runs on a single thread by default. CPU-intensive loops without yielding control will freeze the UI, preventing progress updates and user interaction.
   • Fix: Use Task.Delay or await Task.Yield() periodically in tight loops to yield control back to the scheduler. Avoid synchronous blocking calls like .Result or .Wait().

2. State Volatility on Refresh

   • Explanation: Browser refreshes or navigation clear the in-memory job state. Users may lose track of long-running jobs if the page reloads.
   • Fix: Implement a persistence layer using LocalStorage or IndexedDB. Serialize job state on changes and restore it during initialization. WJb can be extended with custom persistence providers.

3. Payload Serialization Limits

   • Explanation: Large payloads increase memory usage and serialization overhead. Passing entire datasets in the payload can degrade performance.
   • Fix: Keep payloads minimal. Pass references or IDs instead of data. Fetch required data inside the task execution using the payload identifiers.

4. Event Handler Memory Leaks

   • Explanation: Failing to unsubscribe from OnStateChange or similar events causes the component instance to remain in memory, leading to gradual performance degradation.
   • Fix: Always implement IDisposable in components that subscribe to engine events. Unsubscribe in the Dispose method.

5. Silent Failures

   • Explanation: Exceptions thrown within a task may not propagate to the UI, leaving jobs in a stuck state or failing silently.
   • Fix: Wrap task logic in try-catch blocks. Use context.Fail(exception.Message) to transition the job to a failed state and provide feedback. Configure global error handlers if supported by the engine.

6. Concurrency Saturation

   • Explanation: Scheduling too many jobs simultaneously can exhaust browser resources, causing the tab to become unresponsive.
   • Fix: Configure MaxConcurrency in the engine options. Implement backpressure logic in the UI to queue jobs locally before scheduling them with the engine.

7. UI Update Throttling

   • Explanation: Reporting progress too frequently (e.g., every millisecond) can cause excessive re-renders, leading to UI jitter and performance issues.
   • Fix: Throttle progress reports. Only call ReportProgress when the percentage changes significantly or at fixed time intervals.

Production Bundle

Action Checklist

• Register Services: Add AddWjbEngine to Program.cs with appropriate concurrency and retry settings.
• Define Tasks: Create task classes implementing IJobTask<TPayload> with proper error handling and progress reporting.
• Implement Disposal: Ensure all components subscribing to engine events implement IDisposable and unsubscribe correctly.
• Configure Persistence: If offline resilience is required, implement a persistence provider to save and restore job state.
• Throttle Updates: Review progress reporting logic to avoid excessive UI re-renders.
• Test Concurrency: Verify behavior under load by scheduling multiple jobs and checking resource usage.
• Handle Cancellation: Ensure tasks check IsCancellationRequested and exit gracefully when aborted.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Heavy CPU Processing	WJb with Task.Yield	Keeps UI responsive; avoids server costs	Zero infrastructure cost
Offline-First App	WJb + IndexedDB Persistence	Jobs survive refresh and work offline	Minimal storage cost
High Volume Batch	Server-Side Queue	Browser resources limited; server scales better	Higher infrastructure cost
Real-Time Progress UI	WJb Event Subscription	Instant updates without polling	No network cost
Multi-User Sync	Server-Side Queue	Browser state is isolated per user	Higher infrastructure cost

Configuration Template

Use this template to configure WJb with production-grade settings.

// Program.cs
using WJb.Core;
using WJb.Configuration;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWjbEngine(options =>
{
    // Limit concurrent jobs to prevent UI freezing
    options.MaxConcurrency = Environment.ProcessorCount > 1 ? 4 : 2;
    
    // Automatic retry for transient failures
    options.DefaultRetryPolicy = new RetryPolicy
    {
        MaxAttempts = 3,
        BackoffStrategy = BackoffStrategy.Exponential,
        InitialDelay = TimeSpan.FromSeconds(1)
    };

    // Enable persistence for job state recovery
    options.PersistenceProvider = new IndexedDbPersistenceProvider("WJbStore");
    
    // Logging for debugging
    options.EnableDiagnostics = true;
});

await builder.Build().RunAsync();

Quick Start Guide

1. Install Package: Add the WJb NuGet package to your Blazor WASM project.

   dotnet add package WJb
   

2. Register Engine: Call builder.Services.AddWjbEngine() in Program.cs.
3. Create Task: Implement a class inheriting from IJobTask<TPayload> with your logic.
4. Inject Scheduler: Use @inject IJobScheduler Scheduler in your Razor component.
5. Schedule Job: Call Scheduler.Schedule<TaskType, PayloadType>(payload) to start execution.
6. Bind UI: Subscribe to Scheduler.OnStateChange and render job status using Scheduler.ListAll().

This approach enables robust, serverless background processing directly within Blazor WebAssembly, leveraging browser capabilities to deliver responsive, offline-capable applications with minimal infrastructure overhead.