ResearchCave.ErrorHandling (1.1.68)
Installation
dotnet nuget add source --name ResearchCave --username your_username --password your_token https://git.researchcave.com/api/packages/ResearchCave/nuget/index.jsondotnet add package --source ResearchCave --version 1.1.68 ResearchCave.ErrorHandlingAbout this package
Standardized ProblemDetails and HTML error responses for ResearchCave ASP.NET Core services.
ResearchCave.ErrorHandling
ResearchCave.ErrorHandling provides one infrastructure-level error pipeline for ResearchCave ASP.NET Core 10 applications. It handles unhandled exceptions and empty 4xx/5xx responses from MVC, Razor Pages, Minimal APIs, and other middleware without introducing a custom JSON contract.
Registration
using ResearchCave.ErrorHandling;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddResearchCaveErrorHandling();
var app = builder.Build();
// Register before endpoints so exceptions and empty error responses are observed.
app.UseResearchCaveErrorHandling();
app.MapControllers();
app.Run();
The service registration uses ASP.NET Core's IExceptionHandler and IProblemDetailsService. The pipeline uses the framework exception handler and StatusCodePages; it does not replace an intentional response body or change headers already set by the application. Registration also enables ApiBehaviorOptions.SuppressMapClientErrors so MVC leaves empty client-error results for this shared negotiation pipeline instead of eagerly creating its own JSON body.
Content negotiation
Accept: application/jsonorAccept: application/problem+jsonreturns RFCProblemDetailswithContent-Type: application/problem+json.Accept: text/htmlreturns a responsive, dependency-free ResearchCave error page with the corporate logo embedded in the package.- HTML responses use distinct static designs for 401, 403, 404, and other 4xx statuses. The existing animated design remains the 5xx template.
- A missing Accept header or
Accept: */*defaults to JSON below/apiand HTML elsewhere. - Explicit media types and quality values take precedence over wildcard defaults. Equal preferences use the route default.
HEADresponses receive the negotiated status and content type without a response body.
Generated responses include a safe description and a traceId by default. Exception messages, exception types, stack traces, inner exceptions, paths, SQL details, and service internals are never sent to the client. Full exceptions are logged through ILogger with the same trace ID.
Configuration
builder.Services.AddResearchCaveErrorHandling(options =>
{
options.ApiPathPrefix = "/api";
options.IncludeTraceId = true;
options.ApplicationName = "Sentient";
options.HomeUrl = "/"; // Use null to hide the Home button.
options.StatusDescriptions[418] = "The request cannot be completed right now.";
options.MapException<PurchaseConflictException>(StatusCodes.Status409Conflict);
});
Built-in exception mappings are intentionally limited:
| Exception | Status |
|---|---|
ResourceNotFoundException |
404 |
UnauthorizedAccessException |
403 |
ArgumentException |
400 |
NotImplementedException |
501 |
TimeoutException |
504 |
Derived exception types inherit the nearest class mapping. Unmapped exceptions remain 500 Internal Server Error. Applications should add a mapping only when the exception has stable HTTP semantics.
Pipeline behavior
Empty responses such as NotFound(), Unauthorized(), Forbid(), and StatusCode(503) receive a negotiated body. Responses that already have a body, content type, content length, or have started are left unchanged. Existing semantic headers such as WWW-Authenticate, Allow, Retry-After, and Location are preserved.
Call UseResearchCaveErrorHandling() early enough to wrap endpoint execution. Middleware that must be covered by exception handling should be registered after it.