CoreEx.AspNetCore 4.0.0-preview-1

CoreEx.AspNetCore

Provides the ASP.NET Core integration layer for CoreEx: the WebApi execution helper (MVC and Minimal API variants), middleware for ExecutionContext scoping and exception-to-ProblemDetails translation, idempotency key handling, health check configuration, and OpenAPI/NSwag extensions.

Overview

CoreEx.AspNetCore is the server-side HTTP integration package. It bridges CoreEx domain logic — semantic exceptions, Result<T> pipelines, paging, entity contracts — into ASP.NET Core HTTP responses, following RFC 7807 ProblemDetails conventions throughout.

The centrepiece is WebApi, which controllers and Minimal API handlers inject and call (GetAsync, PostAsync, PutAsync, PatchAsync, DeleteAsync). WebApi handles request body deserialization, ETag/If-Match concurrency checking, Result<T> unwrapping, paging header stamping, info/warning message header propagation, and exception-to-ProblemDetails translation — all in a single invocation boundary so individual action methods stay focused on business logic.

Two concrete WebApi implementations ship: Mvc.WebApi returning IActionResult for MVC controllers, and Http.WebApi returning IResult for Minimal API endpoints. Both share the same abstract base (WebApi<TResult>) and invoker infrastructure.

Key capabilities

• 🌐 WebApi execution helper: WebApi encapsulates GET/HEAD, POST (with idempotency), PUT, PATCH (JSON Merge Patch), and DELETE patterns with standardized request validation, deserialization, ETag checks, and response serialization.
• 📄 RFC 7807 ProblemDetails: All IExtendedException types (ValidationException, NotFoundException, ConcurrencyException, etc.) are translated to typed ProblemDetails responses with appropriate HTTP status codes and optional field-level errors extension.
• 🔁 JSON Merge Patch (PATCH): WebApi.PatchAsync reads the request body as a merge-patch document, deserializes the current entity via a provided function, applies the patch, and re-validates before saving.
• ⚙️ ExecutionContext middleware: ExecutionContextMiddleware resolves the DI-scoped ExecutionContext per request, wires ServiceProvider, and propagates info/warning messages to response headers on completion.
• 🛡️ Idempotency key middleware: IdempotencyKeyMiddleware + [IdempotencyKey] attribute intercepts POST operations, checks a pluggable IIdempotencyProvider for a prior response, and either replays the cached result or executes and caches the new one.
• ♥ Health check endpoints: HealthCheckOptions configures /health/live, /health/startup, /health/ready, and /health/detail endpoints with tag-based filtering, JSON detail output, and per-endpoint enable/disable.
• 🏷️ MVC attributes: [PagingAttribute], [QueryAttribute], [AcceptsAttribute], [ProducesNotFoundProblem], and [IdempotencyKey] enrich OpenAPI/NSwag output without cluttering action signatures.
• 🔍 OpenAPI extensions: OpenApiOptions and AspNetCoreExtensions wire NSwag operation processors that read CoreEx MVC attributes and add paging/query parameters, idempotency-key headers, and standard error response types to the generated spec.
• 📡 OpenTelemetry: CoreExAspNetCoreExtensions.AddCoreExAspNetCoreOpenTelemetry wires CoreEx WebApiInvoker activity sources into the OTEL tracer provider.

Key types

Namespaces

Related Namespaces

• CoreEx - Semantic exceptions, ExecutionContext, Result<T>, and PagingArgs are the domain primitives translated by this package into HTTP responses.
• CoreEx.Http - Client-side TypedHttpClientBase<TSelf> consumes ProblemDetails responses produced by this package; HttpNames defines the shared header/query-string constants.
• CoreEx.Validation - ValidationException raised by validators is translated to 400 Bad Request with a field-level errors extension in ProblemDetails.

Additional Resources

• RFC 7807 — Problem Details for HTTP APIs - The specification implemented by WebApi exception handling.
• ASP.NET Core Health Checks - The underlying infrastructure extended by HealthCheckOptions.

AI Usage Guide

An AGENTS.md file is included with this package. AI coding assistants (GitHub Copilot, Claude, Cursor, etc.) that support workspace-injected package documentation will automatically surface concise usage guidance, code examples, and Do Not rules for this package without requiring a local CoreEx checkout.