CoreEx.Data 4.0.0

CoreEx.Data

Provides the IUnitOfWork transactional orchestration contract, DataResult mutation outcome types, data model base classes, and the QueryArgsConfig / QueryFilterParser / QueryOrderByParser pipeline for safe, explicitly-configured OData-style $filter and $orderby LINQ query translation.

Overview

CoreEx.Data sits between the domain layer and persistence backends (SQL, EF Core, Cosmos). It defines the contracts and utilities that keep application services free of storage-specific types while still enabling rich, safe dynamic querying.

IUnitOfWork is the primary transactional boundary abstraction. Application services call TransactionAsync to scope a sequence of mutations and event enqueuing inside one transaction — regardless of whether the underlying store is SQL Server, PostgreSQL, or EF Core. The Events (IEventQueue) property on IUnitOfWork enables the transactional outbox pattern without coupling the service to any messaging infrastructure.

QueryArgsConfig is a configuration object that defines which fields a caller is allowed to filter and sort on, what operators each field supports, and how each field maps to the underlying model property. At request time, QueryExtensions.BuildQuery(IQueryable, QueryArgs, QueryArgsConfig) parses the $filter and $orderby strings, validates them against the configuration, and appends the equivalent System.Linq.Dynamic.Core predicates to the IQueryable — safely, with no arbitrary field exposure.

Key capabilities

• 🔁 Unit-of-work contract: IUnitOfWork provides TransactionAsync and the Events (IEventQueue) property for transactional outbox event enqueuing; storage implementations are injected and swappable.
• 📦 Mutation result types: DataResult (no value) and DataResult carry a WasMutated flag and optional mutated value, distinguishing "found and deleted" from "not found" without throwing exceptions.
• 🗄️ Data model base classes: ModelBase and ReferenceDataModelBase provide ready-made persistence model types implementing IIdentifier, IChangeLogEx, IETag, and common IReferenceData properties respectively.
• 🔍 Safe dynamic filter parsing: QueryFilterParser parses OData-like $filter expressions against an explicit field allow-list, translates them to LINQ predicates, and rejects unknown fields or disallowed operators with structured parse errors.
• 📐 Safe dynamic order-by parsing: QueryOrderByParser parses $orderby expressions against an explicit field allow-list and translates them to LINQ .OrderBy()/.ThenBy() calls.
• ⚙️ Field-level configuration: Each field is configured with its CLR type, allowed operators, model property name/prefix, case normalization, null handling, and custom statement override via a fluent QueryArgsConfig.WithFilter / WithOrderBy builder.
• 🏷️ Reference data filter fields: QueryFilterReferenceDataFieldConfig maps a reference data Code string in the filter to its underlying Id for persistence queries.
• 🔗 IQueryable integration: QueryExtensions.Where and OrderBy applies the filter and order-by to any IQueryable.
• 🧩 Multi-set query contract: IMultiSetArgsCore is the minimal, provider-agnostic base for a single result-set within a multi-set query (MinimumRows, MaximumRows, StopOnNull, InvokeResult()) - CoreEx.Database.Extended.IMultiSetArgs (positional/ordered relational result sets) and CoreEx.Cosmos.Extended.IMultiSetArgs (discriminator-keyed Cosmos DB document sets) each extend it with their own provider-specific matching mechanism, so a future NoSQL provider (e.g. Mongo) can reuse the same base contract and row-count semantics.

Key types

Namespaces

Related Namespaces

• CoreEx - QueryArgs (filter/orderby strings and paging), PagingArgs, and IEventQueue are defined in the root CoreEx package and consumed here.
• CoreEx.Database - IUnitOfWork is implemented by the database unit-of-work; QueryArgsConfig is used by database query builders; Extended.IMultiSetArgs/IMultiSetArgs/MultiSetSingleArgs/MultiSetCollArgs extend IMultiSetArgsCore for positional, ordered relational multi-set queries.
• CoreEx.Cosmos - Extended.IMultiSetArgs/IMultiSetArgs/MultiSetSingleArgs/MultiSetCollArgs extend IMultiSetArgsCore for discriminator-keyed Cosmos DB multi-set queries.
• CoreEx.EntityFrameworkCore - EF Core IQueryable extensions consume QueryArgsConfig via Where/OrderBy.

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.