CoreEx.CodeGen 4.0.0-preview-1

CoreEx.CodeGen

Provides the CoreEx development-time code-generation tooling: a deterministic, schema-driven pipeline that scaffolds the full reference-data implementation — contract, controller, service, repository interface, repository, and mapper — from a single YAML configuration file.

Overview

CoreEx.CodeGen is a console-executable tooling package used during development, not at runtime. It reads a developer-authored ref-data.yaml file (validated against schema/coreex-refdata.json) as its sole configuration source, then produces the .g.cs generated files that implement the complete reference-data layer across the Contracts, Api, Application, and Infrastructure projects of a CoreEx solution.

Generation is orchestrated by OnRamp, which loads ref-data-script.yaml (embedded in the package) to discover the ordered sequence of generation steps. Each step binds a generator class to a Handlebars template and an output path; OnRamp resolves the template, evaluates it against the typed configuration model, and writes the result. Templates reside in RefData/Templates/ and are also embedded so the package is entirely self-contained.

The package exposes CodeGenConsole, a thin wrapper around OnRamp.Console.CodeGenConsole, as its entry point. A consuming project needs only a single Program.cs line to wire up the generator. A secondary Count command is available to report generated vs. hand-authored file and line counts across the solution directories.

Motivation

• Reference data (lookup tables) follows a well-understood, deterministic pattern: each entity needs a contract class, a controller route, a service method, a repository interface, a repository implementation, and a mapper. Writing these by hand is repetitive and error-prone.
• Centralising the pattern in code-generation ensures every entity is consistent — identical structure, naming conventions, route patterns, and EF mapping — with no room for per-entity drift.
• The YAML input and JSON schema act as a concise, reviewable declaration of the domain's reference data catalogue; the generated output is an artefact, not something developers need to maintain.
• Embedding the script and templates inside the NuGet package means consuming projects carry no additional files — only a ref-data.yaml and a one-line Program.cs.

Key capabilities

• 📄 Schema-validated YAML input: ref-data.yaml is validated against schema/coreex-refdata.json; the schema covers root settings (domain, idType, collectionSortOrder, route, routeConvention, repository) and per-entity / per-property overrides.
• 🔧 Script-driven generation: ref-data-script.yaml (embedded) defines the ordered generation steps — contract, controller, service, repository interface, repository, and mapper — each bound to a generator class and a Handlebars template.
• 📐 Handlebars templates: six .hbs templates (embedded in RefData/Templates/) produce idiomatic CoreEx C# across all target layers; output files carry a .g.cs suffix to clearly distinguish generated from hand-authored code.
• 🏗️ Multi-layer output: a single run generates artefacts across four project directories — Contracts, Api, Application, and Infrastructure — all resolved automatically from the CodeGen project's location by convention.
• 🗺️ EF Core mapper generation: the MapperGenerator emits a typed mapper per entity, with per-property mapping directives derived from the PropertyConfig; entities can opt out via excludeMapper: true.
• 📊 Code-count reporting: the Count command walks the solution output directories and reports total vs. generated file and line counts per directory, helping track the proportion of the codebase that is generated.

Usage

A CodeGen project is a minimal console executable that references this package. Create a project at e.g. My.App.Sales.CodeGen, add the project reference, then write:

Program.cs

await CoreEx.CodeGen.CodeGenConsole.Create().RunAsync(args);

ref-data.yaml — place alongside Program.cs:

collectionSortOrder: Code
repository: EntityFramework
entities:
- name: Status
- name: Region
  properties:
  - name: CountryCode
    type: ^Country
- name: Currency
  plural: Currencies
  idType: Guid

Run from the project directory:

dotnet run

The generator resolves the Contracts, Api, Application, and Infrastructure project directories relative to the CodeGen project's location by convention (e.g. ../My.App.Sales.Contracts, ../My.App.Sales.Api, etc.), then writes .g.cs files into the appropriate sub-folders.

To report code counts instead of generating:

dotnet run -- count

Schema

The schema/coreex-refdata.json JSON Schema defines the structure and validation rules for ref-data.yaml. The hierarchy is as follows:

CodeGeneration
└── Entity(s)
  └── Property(s)

Configuration details for each of the above are as follows:

• CodeGeneration
• Entity
• Property

Key types

Namespaces

Additional Resources

• OnRamp — the underlying code-generation orchestration framework used to load the script, resolve templates, and manage file output.
• CoreEx ref-data schema — JSON Schema for ref-data.yaml; use it with IDE YAML language-server support for validation and auto-complete while authoring configuration.

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.