Regira.Entities 6.1.2

Regira Entities

Regira Entities is a generic, extensible framework for managing data entities in .NET applications. It provides a standardized way to handle CRUD operations, filtering, sorting, and includes, while allowing customization through generic type parameters, interfaces and specialized helper services.

Installation

The core abstractions ship as Regira.Entities. The setup below additionally requires the DI, EF Core, and Web sibling packages:

<PackageReference Include="Regira.Entities" Version="6.*" />


<PackageReference Include="Regira.Entities.DependencyInjection" Version="6.*" />
<PackageReference Include="Regira.Entities.EFcore" Version="6.*" />
<PackageReference Include="Regira.Entities.Web" Version="6.*" />

Core Concepts

Generic Type Parameters

Understanding the generic type system is crucial:

Architecture

• IEntityService is the central contract of this framework. Register an implementation for it — and all CRUD operations, filtering, sorting, and includes are handled through that single interface.
• EntityRepository provides the default implementation, but any custom class can be used instead.
• For APIs, using EntityControllerBase is sufficient: it registers the IEntityService automatically, requiring no additional wiring. The controller's generic type arguments must match those used when configuring the entity (see example below).

Main functionality of the service:

Processing Pipeline

Assuming a Repository with a DbContext is being used.

Read Pipeline:

1. EntitySet
2. QueryBuilders
   1. Filters
   2. Sorting
   3. Paging
   4. Includes
3. Processors
4. Mapping (+AfterMapping)*

Write Pipeline:

1. Input
2. Mapping (+AfterMapping)*
3. Preppers (Repository)
4. SaveChanges (DbContext)
   1. Primers (Interceptors)
   2. Submit changes

*: only executed when using API controllers

Pipeline Details:

• QueryBuilders: Build IQueryable based on SearchObject, SortBy & Includes
• Processors: Modify entities after fetching (e.g. setting non-mapped properties)
• Preppers: Executed by the Repository before saving to prepare entities
• Primers: EF Core SaveChangesInterceptors triggered by DbContext when executing SaveChanges
• AfterMapper: Decorates DTOs or Entities after Mapper completes (e.g. calculating URIs)

Dependency Injection

basic sample setup which whill register a IEntityService for Category, Product and Order entities, using the default EntityRepository implementation.

builder.Services
    .UseRegira(LICENSE) // free tier and trial available
    .UseEntities<MyDbContext>(options => options.UseDefaults())
    .For<Category>()
    .For<Product, int, ProductSearchObject>(item => {
        // inline configuration
        item.SortBy(query => query.OrderBy(x => x.Title));
        item.Includes((query, _) => query.Include(x => x.Category));
        item.Filter((query, so) =>
        {
            if (so?.CategoryId?.Any() == true)
              query = query.Where(x => so.CategoryId.Contains(x.CategoryId));
            return query;
        });
    })
    .For<Order, int, OrderSearchObject, OrderSortBy, OrderIncludes>(item => {
        // external classes for configuration
        item.AddSortBy<OrderSortedBuilder>();
        item.AddIncludes<OrderIncludableBuilder>();
        item.AddFilter<OrderQueryFilter>();
        // OrderRepository will handle OrderItems
        item.Related(c => c.OrderItems);
    });

// controllers
[ApiController, Route("categories")]
public class CategoryController : EntityControllerBase<Category>;
[ApiController, Route("products")]
public class ProductController : EntityControllerBase<Product, int, ProductSearchObject, ProductDto, ProductInputDto>;
[ApiController, Route("orders")]
public class OrderController : EntityControllerBase<Order, int, OrderSearchObject, OrderSortBy, OrderIncludes, OrderDto, OrderInputDto>;

Free tier available: this package (Regira.Entities) is Apache-2.0 — the abstractions are free to reference anywhere. The implementation packages (Regira.Entities.EFcore, Regira.Entities.DependencyInjection, Regira.Entities.Web, the mapping packages) carry the Regira Commercial License; the registration package Regira.Entities.DependencyInjection validates keys, with a free tier of 5 simple + 2 complex entity registrations per application, and a license key is required beyond that. Register the key with services.UseRegira(configuration) (reads Regira:LicenseKeys) before calling UseEntities(). Without a key the free tier applies automatically. Obtain a key at https://regira.com/licensing.

Paging defaults: set options.DefaultPageSize / options.MaxPageSize in the UseEntities() callback (or per entity with e.SetPageSize(...)) so List/Search endpoints page automatically instead of returning the full set. See Web Endpoints → Paging.

AI-assisted setup: connect the hosted Regira MCP server (https://mcp.regira.com/mcp) and your coding agent can search these docs, fetch examples, and scaffold entities end-to-end — see the setup guide.

Overview

1. Index — Overview of Regira Entities
2. Entity Models — Creating and structuring entity models
3. Services — Implementing entity services and repositories
4. Mapping — Mapping Entities to and from DTOs
5. Web Endpoints — Exposing entity operations as HTTP endpoints
6. Normalizing — Data normalization techniques
7. Attachments — Managing file attachments
8. Built-in Features — Ready to use components
9. Checklist — Step-by-step guide for common tasks
10. Practical Examples — Complete implementation examples

License

Apache License 2.0 — this package contains no license validation and no runtime limits. See LICENSE. A few companion packages are commercially licensed with a free tier; see the licensing overview.