Regira-Packages

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:

<!-- Core abstractions and base types -->
<PackageReference Include="Regira.Entities" Version="6.*" />

<!-- Required for the sample below -->
<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:

Type	Required	Purpose	Default (when omitted)	Example
TEntity	✓	The entity class	-	Product
TKey	○	Primary key type	int	Guid, int
TSearchObject	○	Advanced filtering	SearchObject	ProductSearchObject
TSortBy	○	Sorting enum	EntitySortBy	ProductSortBy
TInclude	○	Navigation properties enum	EntityIncludes	ProductIncludes
TDto	○	Read/display model (details & lists)	TEntity	ProductDto
TInputDto	○	Create/update model	TEntity	ProductInputDto

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:

Action	Purpose
Details	Get a single item by ID, with all registered Navigation properties included (RefetchAfterSave, globally or via SetReadBehavior(...) per entity, tunes the save endpoints’ response re-fetch)
List	Get a (filtered, sorted & paged) collection of items, usually with limited or no Navigation properties
Save	Create or Update an item, usually Navigation properties are excluded (when updating). However, child collections can be included
Remove	Delete an item

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.

```csharp no-compile builder.Services .UseRegira(LICENSE) // free tier and trial available .UseEntities(options => options.UseDefaults()) .For() .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(); item.AddIncludes(); item.AddFilter(); // OrderRepository will handle OrderItems item.Related(c => c.OrderItems); });

// controllers [ApiController, Route(“categories”)] public class CategoryController : EntityControllerBase; [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.

This site is open source. Improve this page.