CoreEx 4.1.0

CoreEx

The foundational CoreEx package providing the core runtime primitives, patterns, and abstractions used across all other CoreEx libraries and consuming services.

Overview

CoreEx is the shared kernel of the CoreEx framework. It defines the types that all other packages depend on and that consuming applications interact with every day: semantic exception types, execution context, railway-oriented result types, entity contracts, mapping, JSON utilities, hosting infrastructure, caching abstractions, localization, and more.

The package is deliberately non-opinionated — nothing forces a particular architectural style and every capability is opt-in. Teams can adopt individual namespaces incrementally, composing only what they need without taking on the full framework surface area at once.

All other CoreEx packages (CoreEx.Events, CoreEx.Database, CoreEx.AspNetCore, etc.) depend on this package, making it the natural starting point when working with the CoreEx ecosystem.

Motivation

• Reduce boilerplate — recurring patterns such as exception-to-HTTP-status mapping, entity identity, ETag handling, and audit change-log tracking are defined once and reused everywhere rather than reimplemented per project.
• Standardize errors — a rich hierarchy of semantic exception types with built-in HTTP status codes and structured error payloads removes the need for bespoke error-handling middleware.
• Explicit, expected errors — the Result/Result<T> types bring railway-oriented programming to service code, allowing known business errors to be propagated without the overhead and noise of exceptions.
• Execution context — a consistent, AsyncLocal-based ambient context carries user identity, tenant, timestamps, and operation type across the full call chain without threading them explicitly through every method signature.
• Composability — DI registration attributes, invoker tracing, and host-settings primitives are intentionally thin so they integrate into any host model without dictating structure.

Key capabilities

• 🚨 Semantic exceptions: A hierarchy of typed exceptions (ValidationException, NotFoundException, BusinessException, ConcurrencyException, etc.) each with a pre-mapped HTTP status code, structured error type, and configurable logging enablement.
• 🔐 Execution context: An AsyncLocal-scoped ExecutionContext that carries user identity (AuthenticationUser), tenant ID, operation type, request timestamp, and arbitrary attributes throughout the lifetime of a request.
• 🚂 Railway-oriented results: Result and Result<T> value types that represent success or a typed error without throwing, enabling functional pipeline-style error propagation for expected business outcomes.
• 📦 Entity contracts: Interfaces and types for identifiers (IIdentifier<T>), ETags (IETag), audit change logs (IChangeLog), composite keys (CompositeKey), and entity cleaning/transformation — used as the common contract shape across all CoreEx layers.
• 🗺️ Explicit mapping: Uni- and Bi-directional mapper base classes and a Mapper utility for propagating standard contract properties (identity, ETags, change logs, tenant, partition) between source and destination types without a reflection-heavy mapping library.
• 🔄 JSON utilities: RFC 7396 JSON Merge Patch (JsonMergePatch), include/exclude JSON property filtering (JsonFilter), and custom converters for common CoreEx types.
• 💉 DI lifetime attributes: [ScopedService], [SingletonService], and [TransientService] attributes that mark implementation types for automatic discovery and registration via AddDynamicServicesUsing<T>.
• ⏱️ Hosting and work orchestration: Base classes for timer-driven and synchronized hosted services, plus WorkOrchestrator for tracking long-running distributed work states with pluggable storage.
• ⚡ Caching abstractions: IHybridCache and ICacheKeyProvider decouple cache consumption from provider implementation, supporting both in-process and distributed cache strategies.
• 🌐 Localization: LText and TextProvider provide a lightweight, key-based localization abstraction used throughout validation messages, exception text, and reference data.
• 🃏 Wildcard parsing: Wildcard provides standardized * and ? wildcard parsing, validation, and Regex compilation for consistent wildcard-based filtering.
• 🏷️ Reference data interfaces: Core IReferenceData, IReferenceDataCollection, and ReferenceDataOrchestrator types establish the reference data contract used by CoreEx.RefData and data-layer packages.
• 📐 Schema versioning: SchemaAttribute and Schema utilities for associating a semantic version with entity types, supporting schema-aware messaging and validation.

Key types

See the Extended Exceptions section below for the full list of semantic exception types.

Validating HTTP response values

HTTP success and JSON deserialization do not guarantee a valid dependency response. Use WithValidator with a CoreEx.Validation.IValidator<T> to opt into response-contract validation:

using var response = await _httpClient.GetAsync($"api/customers/{Uri.EscapeDataString(id)}", ct).ConfigureAwait(false);
return await response.WithValidator(customerValidator).ToResultAsync(ct).ConfigureAwait(false);

The typed wrapper reuses the existing response converters and validates only successful, non-null deserialized values. It returns the validation result's Value, including replacements or normalization. ToResultAsync requires a non-null value both before and after validation; ToResultOrDefaultAsync allows null and skips validation when the response has no value. GetValueAsync and GetValueOrDefaultAsync provide the throwing equivalents. All four methods accept optional JSON serializer options and a cancellation token.

Reported validation errors become HttpRequestException failures with the validation exception as the inner exception, preserving structured messages. ToResult* returns these failures; GetValue* throws them. Under standard CoreEx API exception handling, these are internal 500 errors, not caller 400 validation errors. The exception's upstream status is diagnostic context, not the status returned to the caller. Outer messages do not contain the response body. Existing HTTP/ProblemDetails handling is unchanged; cancellation, deserialization exceptions, and unexpected exceptions thrown by a validator still propagate.

Use a response-specific validator rather than assuming create/update rules apply to read responses. For small client-only rules, prefer a private static readonly Validator<T> configured once with Validator.Create<T>().HasProperty(...) from the CoreEx.Validation package inside the Infrastructure client:

private static readonly Validator<Customer> _validator = Validator.Create<Customer>()
    .HasProperty(x => x.Email, c => c.Mandatory().Email());

// Inside the asynchronous HTTP client method.
using var response = await _httpClient.GetAsync($"api/customers/{Uri.EscapeDataString(id)}", ct).ConfigureAwait(false);
return await response.WithValidator(_validator).ToResultAsync(ct).ConfigureAwait(false);

Extract a colocated validator only for substantial rules or genuine reuse. Validate consumed fields rather than requiring every DTO property or matching identifiers by default. Configure shared rules once without captured request state or scoped dependencies, and test inline rules through client unit tests rather than exposing them solely for testing. Invalid responses must not be cached. See the Customers client sample for a complete implementation. Validators can normalize values or perform I/O, so consider their effects explicitly. The wrapper does not own or dispose the response, cache validation results, or support concurrent response consumption. Keep responsibility for disposing the response at the call site. Like the underlying converters, a terminal operation consumes the content stream; creating a wrapper does not buffer the body for repeated reads.

Errors vs Exceptions

CoreEx distinguishes between expected and unexpected errors:

Extended Exceptions

Semantic (error-oriented) exception types with automatic HTTP status mapping:

All inherit from ExtendedException<TSelf> implementing IExtendedException.

Additionally, these support With*-style methods to add additional context that is added to the resulting ProblemDetails:

throw new BusinessException($"Product '{movement.ProductId}' does not have sufficient quantity on hand.")
    .WithErrorCode("insufficient-quantity")
    .WithKey(movement.ProductId);

The above would result in the following ProblemDetails:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Product \u002700000001-0000-0000-0000-000000000000\u0027 does not have sufficient quantity on hand.",
  "status": 400,
  "traceId": "00-a8e8623ef74c2b53820d0ff5d799850d-df28b0bc787429f5-01",
  "errorType": "business",
  "errorCode": "insufficient-quantity",
  "key": "00000001-0000-0000-0000-000000000000"
}

Namespaces

Related Namespaces

• CoreEx.AspNetCore - ASP.NET Core integration: WebApi HTTP helpers, IExtendedException middleware, and ExecutionContext middleware binding.
• CoreEx.Validation - Full validation rule engine built on top of the IValidator<T> contract defined in this package.
• CoreEx.Events - Event publishing and subscribing built on top of the ExecutionContext, Result, and entity contracts from this package.
• CoreEx.Database - Database access layer built on the data primitives (PagingArgs, QueryArgs, IIdentifier) defined here.
• CoreEx.EntityFrameworkCore - Entity Framework Core integration consuming the entity contracts and mapping types from this package.
• CoreEx.RefData - Full reference data implementation extending the IReferenceData and ReferenceDataOrchestrator types defined here.
• CoreEx.UnitTesting - Test helpers and fluent assertion extensions targeting the types and patterns from this package. (test only)

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.