NT.Blazor.ErrorBoundary.AspNetCore 1.0.0

NT.Blazor.ErrorBoundary

Reusable Blazor error-boundary reporting with a WebAssembly-safe core package and optional ASP.NET Core logging integration. The component renders generic fallback UI by default and reports failures through ILogger or a configurable HTTP endpoint without depending directly on Application Insights or OpenTelemetry SDKs.

Packages

Both packages target .NET 9 and .NET 10. The ASP.NET Core package depends on the core package, so installing it in a server project provides both. Install the core package directly in a separate .Client or standalone WebAssembly project.

# Server or API project
dotnet add package NT.Blazor.ErrorBoundary.AspNetCore

# Separate .Client or standalone WebAssembly project
dotnet add package NT.Blazor.ErrorBoundary

Choose the setup for your render mode

Complete error-boundary setup for a Blazor Web App

This is the typical setup for a Blazor Web App that uses Interactive Server, Interactive WebAssembly, or Interactive Auto render modes.

1. Configure the server project

Install NT.Blazor.ErrorBoundary.AspNetCore in the server project, then register the server reporter before building the application. The report path is host-owned and can be changed to match the application's API conventions.

using NT.Blazor.ErrorBoundary.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddBlazorErrorBoundaryServerLogging("/api/blazor-errors");

var app = builder.Build();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode();

app.MapBlazorErrorBoundaryTelemetry();

app.Run();

AddBlazorErrorBoundaryServerLogging performs three registrations:

• It registers NTBlazorServerErrorReporter as the scoped INTBlazorErrorReporter used during server rendering.
• It stores the report path used by MapBlazorErrorBoundaryTelemetry.
• It reads IHostEnvironment so exception details are rendered by default only in Development.

MapBlazorErrorBoundaryTelemetry maps a JSON POST endpoint at the configured path. Successful reports return 204 No Content and are written through ILogger.

If the application never uses a WebAssembly render mode, calling MapBlazorErrorBoundaryTelemetry is optional. Server-side exceptions are logged directly and do not make an HTTP round trip.

2. Configure the .Client project

Install NT.Blazor.ErrorBoundary in the client project and register the HTTP reporter in its Program.cs.

using Microsoft.Extensions.DependencyInjection;

var builder = WebAssemblyHostBuilder.CreateDefault(args);

builder.Services
    .AddNTBlazorErrorBoundaryHttpClient("/api/blazor-errors", builder.HostEnvironment.Environment)
    .ConfigureHttpClient(client => {
        client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress);
    });

await builder.Build().RunAsync();

The base address is required when reportUri is relative. An absolute report URI can be used instead, in which case the reporter does not require BaseAddress.

The environment name controls the default exception-detail behavior in the browser. Pass builder.HostEnvironment.Environment so DevelopmentOnly behaves consistently between the server and client DI containers.

For cross-origin APIs, use an absolute endpoint URI and configure CORS on the API host. If the endpoint requires authentication, configure the returned IHttpClientBuilder with the application's authorization message handler.

3. Add the boundary to the component tree

Place NTErrorBoundary around the part of the component tree that should fail and recover together. Wrapping the layout body is a common application-wide boundary.

@using NT.Blazor.ErrorBoundary.Components
@inherits LayoutComponentBase

<NTErrorBoundary>
    @Body
</NTErrorBoundary>

You can instead wrap Routes, a page, or a smaller feature. Smaller boundaries isolate failures so the rest of the page remains usable.

When a descendant throws, the default fallback:

• Displays a generic message.
• Hides exception details unless they are explicitly enabled or the environment is Development.
• Displays a Try again button for interactive rendering.
• Displays a Reload page link for static rendering.
• Attempts to report the error without allowing reporting failures to replace the fallback UI.

Interactive Server-only setup

For an application that never activates WebAssembly, only the server registration and component are required.

builder.Services.AddBlazorErrorBoundaryServerLogging("/api/blazor-errors");

@using NT.Blazor.ErrorBoundary.Components

<NTErrorBoundary>
    @Body
</NTErrorBoundary>

The path must be supplied because it is part of the shared options contract, but the endpoint does not need to be mapped when no browser-side reports will be posted.

Standalone WebAssembly with a separate API

Configure the ASP.NET Core API exactly like the server portion of the complete setup:

builder.Services.AddBlazorErrorBoundaryServerLogging("/api/blazor-errors");

var app = builder.Build();

app.MapBlazorErrorBoundaryTelemetry();

Configure the standalone WebAssembly application with the API's absolute URI:

builder.Services.AddNTBlazorErrorBoundaryHttpClient(
    "https://api.example.com/api/blazor-errors",
    builder.HostEnvironment.Environment);

The API host must explicitly allow the WebAssembly application's origin through CORS.

Exception-detail policy

RenderExceptionDetails controls what the default fallback renders:

@using NT.Blazor.ErrorBoundary.Components

<NTErrorBoundary RenderExceptionDetails="ExceptionDetailsMode.Never">
    @Body
</NTErrorBoundary>

The rendering policy affects only the fallback UI. Reports and server logs still contain diagnostic exception fields.

Custom fallback content

NTErrorBoundary inherits Blazor's ErrorBoundary content parameters. Supplying ErrorContent replaces the package's default fallback UI.

@using NT.Blazor.ErrorBoundary.Components

<NTErrorBoundary>
    <ChildContent>
        @Body
    </ChildContent>
    <ErrorContent Context="exception">
        <section role="alert">
            This section is temporarily unavailable.
        </section>
    </ErrorContent>
</NTErrorBoundary>

The exception is still reported before the custom fallback renders. Avoid displaying exception.Message outside a trusted development environment.

Size limits

String fields in an HTTP report and rendered exception details default to a maximum of 16,384 characters. Configure smaller limits after registering the reporter:

using NT.Blazor.ErrorBoundary.Services;

builder.Services.Configure<NTBlazorErrorBoundaryHttpClientOptions>(options => {
    options.MaxReportFieldLength = 4_096;
});
builder.Services.Configure<NTErrorBoundaryOptions>(options => {
    options.MaxExceptionDetailsLength = 4_096;
});

Configure MaxReportFieldLength in both the client and server DI containers when using WebAssembly. The client truncates before sending, and the server truncates again before logging. A limit less than or equal to zero disables truncation.

Logging and telemetry

The package writes through ILogger; the consuming application decides where those logs go.

builder.Logging.AddConsole();
// Add the application's Application Insights, OpenTelemetry, Serilog,
// or other ILogger provider here.

Server-rendered exceptions log the original Exception with these structured scope values:

• BlazorBoundaryName
• BlazorIsInteractive
• BlazorRenderMode
• BlazorUri

Reports received from WebAssembly additionally include:

• BlazorExceptionMessage
• BlazorExceptionStackTrace
• BlazorExceptionType
• BlazorOccurredAtUtc
• RequestId
• RequestMethod
• RequestPath
• UserId, when a ClaimTypes.NameIdentifier or sub claim is present

The HTTP reporter treats network and non-success response failures as reporting failures, logs a warning, and does not rethrow them into the component tree. Cancellation requested by the caller is preserved.

Securing the telemetry endpoint

The package intentionally does not choose authorization, CORS, rate-limiting, or telemetry-retention policy for the host. The mapped endpoint accepts exception messages and stack traces, so treat it as diagnostic ingestion rather than a general public API.

MapBlazorErrorBoundaryTelemetry returns a RouteHandlerBuilder, allowing normal ASP.NET Core endpoint policy:

app.MapBlazorErrorBoundaryTelemetry()
    .RequireAuthorization("BlazorTelemetry")
    .RequireRateLimiting("blazor-telemetry");

Choose policies that match the application:

• Require authorization when browser reports are sent with an authenticated identity.
• Configure the client reporter to attach the corresponding cookie or bearer token.
• Apply rate limits and request-size limits to prevent telemetry abuse.
• Configure CORS explicitly for cross-origin WebAssembly applications.
• Treat logged URIs, exception messages, and stack traces as potentially sensitive data.
• Apply redaction and retention in the configured logging provider.

Data flow

Server-rendered exception:

NTErrorBoundary
    -> INTBlazorErrorReporter
    -> NTBlazorServerErrorReporter
    -> ILogger

WebAssembly exception:

NTErrorBoundary
    -> NTHttpClientBlazorErrorReporter
    -> POST /api/blazor-errors
    -> MapBlazorErrorBoundaryTelemetry
    -> ILogger

Development

The repository uses the SDK selected by global.json and builds both .NET 9 and .NET 10 targets.

dotnet restore ./NT.Blazor.ErrorBoundary.slnx
dotnet build ./NT.Blazor.ErrorBoundary.slnx --configuration Release --no-restore
dotnet test --solution ./NT.Blazor.ErrorBoundary.slnx --configuration Release --no-build --no-restore

Tests use xUnit v3 on Microsoft.Testing.Platform v2. The .NET 10 SDK selects Microsoft.Testing.Platform through global.json; the test projects do not depend on VSTest, Microsoft.NET.Test.Sdk, or Coverlet.

Generate Cobertura coverage with Microsoft's testing-platform coverage extension:

dotnet test --project ./Tests/NT.Blazor.ErrorBoundary.Tests/NT.Blazor.ErrorBoundary.Tests.csproj --framework net10.0 --configuration Release --no-build --no-restore --results-directory ./artifacts/coverage/core --coverage --coverage-output-format cobertura --coverage-output coverage.cobertura.xml
dotnet test --project ./Tests/NT.Blazor.ErrorBoundary.AspNetCore.Tests/NT.Blazor.ErrorBoundary.AspNetCore.Tests.csproj --framework net10.0 --configuration Release --no-build --no-restore --results-directory ./artifacts/coverage/aspnetcore --coverage --coverage-output-format cobertura --coverage-output coverage.cobertura.xml

The full suite validates both target frameworks. Coverage runs once against .NET 10 for each test project so parallel target frameworks cannot overwrite a shared output file. The Build and Pack workflow uploads both reports as the code-coverage artifact.

Warnings are treated as errors across the repository. Packable projects generate XML documentation, so missing or invalid public API documentation also fails the build.

Create local packages with:

dotnet pack ./NT.Blazor.ErrorBoundary/NT.Blazor.ErrorBoundary.csproj --configuration Release --no-build --output ./artifacts/packages
dotnet pack ./NT.Blazor.ErrorBoundary.AspNetCore/NT.Blazor.ErrorBoundary.AspNetCore.csproj --configuration Release --no-build --output ./artifacts/packages

CI and releases

The Build and Pack workflow runs for pull requests and manual validation. It builds, tests, creates both NuGet packages and symbol packages, and uploads them as workflow artifacts.

Publication follows the same preview and stable semantic-release model as NTComponents.

1. Add the NuGet.org API key as the NUGET_API_KEY GitHub Actions secret.
2. Merge release-worthy Conventional Commits into main.
3. Publish Prerelease builds and tests the repository automatically.
4. Semantic-release updates the preview branch and creates a vX.Y.Z-preview.N tag and GitHub prerelease.
5. The same workflow packs both packages with that preview version and publishes them and their symbols to NuGet.org.
6. When the preview is ready, run the manual Release workflow from GitHub Actions.
7. The release workflow builds and tests again, creates the stable vX.Y.Z tag and GitHub release, and publishes both stable packages.
8. After stable publication succeeds, the workflow unlists prerelease versions whose base version is at or below the stable release.

Release calculation follows Conventional Commits:

• fix: creates a patch release.
• feat: creates a minor release.
• BREAKING CHANGE: creates a major release.
• Documentation, CI, and chore-only changes do not create a release by default.

Do not create release tags manually. If a push to main contains no release-worthy commits, semantic-release creates no preview tag and prerelease publication is skipped. If the manual stable release has no release-worthy commits, no stable package is published.