CoreEx.RefData 4.2.0

CoreEx.RefData

Provides the CoreEx reference data framework: typed base classes for reference data items and collections, a hybrid-cache-backed orchestrator, contextual date-validity checking, and a code-serialization collection.

Overview

CoreEx.RefData implements the domain concept of reference data — lookup tables (e.g. Status, Country, Currency) that are read frequently and change rarely. Items carry an Id, a Code, Text, Description, SortOrder, IsActive, and optional StartsOn/EndsOn date range, all of which participate in validity checking via ReferenceDataContext.

Two concrete base classes cover the most common identity types: ReferenceData<TSelf> (string Id) and ReferenceData<TId, TSelf> (arbitrary TId). Each exposes static TryGetById and TryGetByCode helpers that delegate to the ambient ReferenceDataOrchestrator registered in the DI container. Collections are thread-safe dictionaries keyed by both Id and Code; GetItems returns a stable, sorted IEnumerable by ReferenceDataSortOrder.

ReferenceDataHybridCache implements IReferenceDataCache on top of IHybridCache, using per-type semaphores to ensure that only one thread performs the expensive load while others wait, then everyone benefits from the cached result. ReferenceDataCodeCollection<TRef> solves the serialization problem: a property declared as a list of codes is stored as List<string?> on the wire but exposes ICollection<TRef> at the domain level.

Key capabilities

• 📚 Typed reference data base classes: ReferenceData<TSelf> (string Id) and ReferenceData<TId, TSelf> (typed Id) provide Id, Code, Text, Description, SortOrder, IsActive, StartsOn/EndsOn, mapping support, and ThrowIfInactive/ThrowIfInvalid guards.
• 📋 Thread-safe collections: ReferenceDataCollection<TRef> and ReferenceDataCollection<TId, TRef> index items by both Id and Code (case-insensitive by default) and expose GetItems(sortOrder, activeOnly, isValid) for filtered, ordered enumeration.
• 🔄 Hybrid-cache backing: ReferenceDataHybridCache implements IReferenceDataCache via IHybridCache; per-type semaphores prevent thundering-herd on cold start and support configurable entry options per item type via OnCreateCacheEntry.
• 📅 Contextual date validity: ReferenceDataContext supplies the reference date used to evaluate StartsOn/EndsOn on every item; the date can be set globally or overridden per type, defaulting to Runtime.UtcNow.
• 🌐 Localised text and description: Text and Description are resolved through LText on every get, enabling locale-specific display strings without changing the domain model.
• 🏷 Code-serialization collection: ReferenceDataCodeCollection<TRef> stores codes as List<string?> for wire serialization while presenting an ICollection<TRef> interface backed by the live orchestrator lookups.
• 🔧 DI and health-check helpers: AddReferenceDataOrchestrator and related IServiceCollection extensions register the orchestrator, cache, and ReferenceDataQuery.Default (enabling QueryAsync<TRef>() out of the box); ReferenceDataOrchestratorHealthCheck exposes a health-check endpoint reporting all registered reference data types.
• 🔎 OData-esque query/paging: ReferenceDataQuery (the default IReferenceDataQuery implementation) filters, orders, and pages a reference data collection via ReferenceDataQueryArgsConfig — OData-esque $filter on code/text (all string operators, case-insensitive) and $orderby on code/text/sortOrder. Supply a Func<Type, QueryArgsConfig?> to ReferenceDataQuery(configSelector) to use a different config per reference data type.

Reference-data code conversion

The Roslyn generator gives each concrete [ReferenceData] type an implicit conversion from string?:

BasketStatus? status = source.BasketStatusCode;
DiscountCoupon? coupon = source.DiscountCouponCode;

Pass code strings directly to concrete typed reference-data parameters and properties; no RefData<T> wrapper, code-only construction or conversion-only collection lookup is needed. Use an explicitly typed variable or cast when the expression does not provide a concrete target type; generic IReferenceData constraints do not expose concrete generated operators.

Conversion uses the current orchestrator. Null converts to null; unresolved non-null codes produce invalid instances retaining their codes, including when no current orchestrator exists. Requiredness, validity and activity must be checked separately. Use explicit collection lookups when querying the collection or requiring found/not-found semantics.

For a single reference-data field on a contract, declare [ReferenceData<T>] public partial string? XxxCode { get; set; } within a [Contract] partial class, not a plain code auto-property. Set XxxCode when mapping/arranging DTOs; use the generated typed Xxx accessor for reference-data behavior.

Key types

Namespaces

Related namespaces

• CoreEx - Defines IReferenceData, IReferenceDataCollection, IReferenceDataCache, ReferenceDataOrchestrator, and IHybridCache consumed throughout.
• CoreEx.Caching.FusionCache - FusionHybridCache is the recommended IHybridCache implementation for backing ReferenceDataHybridCache in production.

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.