Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Orbis25/FoundationKit/llms.txt

Use this file to discover all available pages before exploring further.

FoundationKit is designed as a modular suite rather than a single monolithic library. Each package has a single responsibility and explicit dependency boundaries, so you can pull in only what your project genuinely needs — a pure data-access layer for a background worker, the full controller stack for a REST API, or just the encryption and enum helpers for a utility library.

Package Overview

FoundationKit

Version: 4.1.0
The umbrella package that pulls in all three sibling packages as project references and adds the controller layer, encryption service, DI extension methods, and the optional AES middleware.
Key types: ApiCoreController<TModel, TService>, ApiMapController<TService, TDto, TInput, TEdit>, MvcCoreController, IEncryptorService, EncryptorService, FoundationKitAesEncryptorMiddleware.Key extensions: AddFoundationKit(Assembly), AddFoundationKitEncryptor(EncryptorOption), AddFoundationKitIdentity<TUser, TDbContext>(), AddFoundationKitIdentityWithMapper<TUser, TDbContext>(Assembly).

FoundationKit.Domain

Version: 4.1.0
Provides the base persistence primitives. Depends on Microsoft.EntityFrameworkCore 8.0.4 and Microsoft.AspNetCore.Identity.EntityFrameworkCore 8.0.4.
Key types: BaseModel (Id, CreatedAt, UpdatedAt, IsDeleted, CreatedBy, UpdatedBy), FoundationKitDbContext, FoundationKitIdentityDbContext<TUser>, EncryptorOption, FoundationKitStaticOptions.

FoundationKit.Repository

Version: 4.1.0
Generic repository abstractions and implementations. Depends on FoundationKit.Domain and AutoMapper 13.0.1.
Key types: IBaseRepository<TModel>, BaseRepository<TContext, TModel>, IMapRepository<TInput, TEdit, TDto>, MapRepository<TContext, TModel, TInput, TEdit, TDto>, PaginationResult<T>, Paginate.

Foundationkit.Extensions

Version: 4.1.0
Pure helpers with no direct EF Core dependency. Depends only on FoundationKit.Domain (for shared value objects) and Microsoft.AspNetCore.Mvc.ViewFeatures 2.2.0.
Key types: AesEncryptionHelper, AesConfig, CipherTweetNaCl, QueryableExtensions (PaginateAsync, Paginate), EnumExtension (GetDisplayName), ControllerExtensions (AesOk).

Installation

dotnet add package FoundationKit
dotnet add package FoundationKit.Domain
dotnet add package FoundationKit.Repository
dotnet add package Foundationkit.Extensions

Package Details

FoundationKit (Core)

The umbrella package is the right choice when you are building a REST API and want the full suite — base controllers, encryption, and DI conveniences — in one install. DI Registration methods
MethodPurpose
AddFoundationKit(Assembly)Registers AutoMapper profiles from your assembly
AddFoundationKitEncryptor(EncryptorOption, ServiceLifetime)Registers IEncryptorService with RSA/AES keys
AddFoundationKitIdentity<TUser, TDbContext>()Wires ASP.NET Core Identity without AutoMapper
AddFoundationKitIdentityWithMapper<TUser, TDbContext>(Assembly)Wires Identity and registers AutoMapper profiles
Base controllers ApiCoreController<TModel, TService> — use when your request/response type is the entity model itself:
[Route("api/[controller]")]
[ApiController]
public abstract class ApiCoreController<TModel, TService> : ControllerBase
    where TModel : BaseModel
    where TService : IBaseRepository<TModel>
ApiMapController<TService, TDtoModel, TInputModel, TEditModel> — use when you separate input, edit, and output DTO types via AutoMapper:
[Route("api/[controller]")]
[ApiController]
public abstract class ApiMapController<TService, TDtoModel, TInputModel, TEditModel> : ControllerBase
    where TInputModel : BaseInput
    where TDtoModel : BaseOutput
    where TEditModel : BaseEdit
    where TService : IMapRepository<TInputModel, TEditModel, TDtoModel>

FoundationKit.Domain

Provides the data model primitives and DbContext bases that every other package builds on. BaseModel — the abstract base all your entities must inherit:
public abstract class BaseModel
{
    public virtual Guid Id { get; set; }
    public virtual DateTime CreatedAt { get; set; }
    public virtual DateTime? UpdatedAt { get; set; }   // override + [Column] to persist
    public virtual bool IsDeleted { get; set; }
    public virtual string? CreatedBy { get; set; }
    public virtual string? UpdatedBy { get; set; }

    [NotMapped] public string CreatedAtStr => CreatedAt.ToString("dd/MM/yyyy hh:mm:ss");
    [NotMapped] public string UpdateAtStr  => UpdatedAt != null ? UpdatedAt.Value.ToString("dd/MM/yyyy hh:mm:ss") : "";
}
FoundationKitDbContext — inherit to get automatic CreatedAt / UpdatedAt stamping and soft-delete query filters:
public class ApplicationDbContext : FoundationKitDbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options) { }

    public DbSet<Person> Persons { get; set; }
}

FoundationKit.Repository

Provides both a direct entity repository and a DTO-mapped repository. IBaseRepository<TModel> — full interface surface:
MethodSignature
CreateAsyncTask<TModel> CreateAsync(TModel, CancellationToken)
UpdateAsyncTask<TModel?> UpdateAsync(TModel, CancellationToken, bool verifyEntity)
UpdatePartialEntityAsyncTask UpdatePartialEntityAsync(TModel, List<Expression<Func<TModel, object?>>>, CancellationToken)
GetByIdAsyncTask<TModel?> GetByIdAsync(Guid, bool asNoTracking, CancellationToken, params includes)
GetAllIQueryable<TModel> GetAll(expression, orderDesc, ordered, params includes)
GetListAsyncTask<IEnumerable<TModel>> GetListAsync(orderDesc, expression, ordered, CancellationToken, params includes)
GetPaginatedListAsyncTask<PaginationResult<TModel>> GetPaginatedListAsync(Paginate, expression, ordered, CancellationToken, params includes)
GetOneAsyncTask<TModel?> GetOneAsync(Expression<Func<TModel, bool>>, CancellationToken)
ExistAsyncTask<bool> ExistAsync(expression, CancellationToken)
CountAsyncTask<int> CountAsync(CancellationToken, params expressions)
SoftRemoveAsyncTask<bool> SoftRemoveAsync(Guid, CancellationToken)
RemoveAsyncTask<bool> RemoveAsync(Guid, CancellationToken)
CommitAsyncTask CommitAsync(CancellationToken)
CommitAndResultAsyncTask<string?> CommitAndResultAsync(CancellationToken) — returns null on success, error message on failure
Paginate — query string model consumed by GetPaginatedListAsync and ApiCoreController:
PropertyTypeDefaultDescription
Pageint1Current page number
Qytint10Items per page
OrderByDescbooltrueSort direction
NoPaginateboolfalseReturn all records when true

Foundationkit.Extensions

Independent helper types that can be used in any .NET 8 project regardless of whether EF Core or the controller layer is present. AES Encryption
// AesConfig holds Key and Iv as Base64 strings
var config = new AesConfig { Key = "...", Iv = "..." };
string encrypted = AesEncryptionHelper.Encrypt("plaintext", config);
string decrypted = AesEncryptionHelper.Decrypt(encrypted, config);
TweetNaCl Cipher (CipherTweetNaCl) Provides asymmetric key-pair generation, encryption, decryption, signing, and signature verification via a managed TweetNaCl implementation. Suitable for peer-to-peer message authentication. QueryableExtensions
// Paginate any IQueryable<T> without a repository
var result = await myQuery.PaginateAsync(new Paginate { Page = 1, Qyt = 20 }, cancellationToken);
// result.Results, result.Total, result.PageTotal, result.ActualPage
EnumExtension
// Returns the [Display(Name = "...")] attribute value, or the enum name as fallback
string label = MyEnum.ActiveUser.GetDisplayName();

Choosing the Right Combination

ScenarioPackages to install
Full REST API — controllers, CRUD, pagination, encryptionFoundationKit (pulls in all others)
API without encryption or IdentityFoundationKit, FoundationKit.Domain, FoundationKit.Repository
Background worker / data-access onlyFoundationKit.Domain, FoundationKit.Repository
API with ASP.NET Core IdentityFoundationKit + call AddFoundationKitIdentity or AddFoundationKitIdentityWithMapper
Utility library — enum helpers, AES, pagination onlyFoundationkit.Extensions (+ FoundationKit.Domain for shared value objects)
DTO-mapped repository with AutoMapperFoundationKit.Repository, FoundationKit.Domain + configure AutoMapper profiles
Installing the umbrella FoundationKit package is the fastest path for new REST API projects. If package size or dependency footprint matters — for example in a Lambda or Azure Function — install FoundationKit.Repository and FoundationKit.Domain directly and skip the controller layer.
The optional FoundationKit.Events package (version 0.1.0) adds RabbitMQ-backed messaging via AddEvents, AddSubscriber, and IRabbitMessageBroker.PublishAsync. It is independent of the four core packages and is not required for basic use.

Build docs developers (and LLMs) love