CoreEx 4.0.0-preview-1

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.

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.