Akay.To.Core 1.1.12

Akay.To.Core

Paquete base de abstracciones compartidas y funcionalidad de propósito general para aplicaciones .NET. No depende de Akay.To.EF ni de Akay.To.Azure: además de sus propias implementaciones (mediator, caché, HTTP, bootstrap de host), define los contratos que otros paquetes implementan.

¿Para qué sirve?

Para construir la capa de aplicación, dominio y host de una API sin reinventar la infraestructura: mediador propio (sin MediatR), result pattern, eventos de dominio, caché, mensajería, seguridad, observabilidad y bootstrap del host.

Funcionalidades

Dispatcher / Mediator (CQRS sin MediatR)

IDispatcher, IStreamDispatcher y IDomainEventPublisher están implementados aquí (Dispatcher, StreamDispatcher, DomainEventPublisher). Implementa IQueryHandler<TQuery, TResponse> o ICommandHandler<TCommand, TResponse> y despacha con IDispatcher.Send() / IStreamDispatcher.Stream(). Los handlers se descubren automáticamente por assemblies.

• Requests (los implementa la app): IRequest, ICommand, ICommand<T>, IQuery<T>, IStreamRequest, IStreamCommand, IStreamQuery
• Handlers (los implementa la app): IRequestHandler, ICommandHandler, IQueryHandler, IDomainEventHandler, IStreamRequestHandler
• Paginación (implementación en Core): PagedQuery / PagedResponse, ContinuationTokenQuery / ContinuationTokenResponse

Pipeline behaviors

Middlewares implementados en Core que se ejecutan alrededor de cada request. Cada uno se activa al implementar su interfaz o registrar un IValidator:

Result Pattern

Devuelve Result<T> / Error en lugar de usar excepciones para flujo de control. Mapea automáticamente a HTTP con ToOk(), ToCreated(), ToNoContent(), ToAccepted(), ToFile().

• Error con ErrorType semántico: Validation, NotFound, Conflict, Unauthorized, Forbidden, Failure, Internal, Timeout, Unavailable, Cancelled
• Composición funcional: Map, Bind, Tap, Match (+ versiones async)

Eventos de dominio

• IDomainEventPublisher → implementado en Core (publicación in-process)
• IDomainEvent / IDomainEventHandler<T> → contratos que implementa la app
• IOutboxDomainEvent / IOutboxMessage / IOutboxEventWriter → contratos en Core; la persistencia en OutboxMessage (misma transacción) la hace Akay.To.EF (DomainEventsSaveChangesInterceptor, OutboxEventWriter)

Mensajería

Abstracciones de bus cuyo proveedor es Akay.To.Messaging.Rebus:

• IMessageBus — SendAsync (comandos) y PublishAsync (eventos pub/sub)
• ICommandMessage, IIntegrationEvent, IMessageHandler<T> (auto-descubrimiento)
• BaseConsumerToDispatcher — implementación en Core (clase base abstracta que traduce mensajes a comandos vía IDispatcher)

Caché híbrida

IHybridCacheService (implementado por HybridCacheService) con dos niveles: L1 en memoria + L2 Redis. Úsala directamente o deja que CacheBehavior la use para requests ICacheable<T>.

HttpClient

Extensiones tipadas que devuelven Result<T>: GetJsonAsync<T>, PostJsonAsync<T>, PutJsonAsync<T>, GetStreamAsync<T>, etc. AddHttpClients() configura un pipeline de resiliencia (retry, circuit breaker, rate limit, timeouts) desde HttpClientSettings.

UserContext

IUserContext / IUserContext<TTenantId> con UserContextBase (clase base abstracta que lee de HttpContext.User). Tu aplicación deriva la clase concreta y la registra con AddUserContext<T>() / AddTenantUserContext<T, TId>().

Entidades de dominio

• Entity<TId> / AggregateRoot<TId> — entidades base con AddDomainEvent() (implementación en Core)
• IAuditable / IUserAuditable, ISoftDeletable / IUserSoftDeletable, IHasTenant, IHasOwner, ITrackChanges, IHasSyncId — contratos que implementa la app; los interceptores de Akay.To.EF los consumen (auditoría, soft delete, tenant/owner, change tracking)

Identity

IExternalIdentityProvisioningService + ExternalUserRequest + ExternalIdentityErrors para crear/actualizar/desactivar usuarios en proveedores de identidad externos. Implementado por Akay.To.Azure (EntraIdUserProvisioningService).

JWT

IJwtTokenGenerator (implementado por JwtTokenGenerator) — genera tokens firmados (HS256) con claims de usuario y roles, desde JwtSettings.

Abstracciones de Azure y AI

Interfaces que implementan los paquetes de infraestructura:

• Blob Storage (→ Akay.To.Azure): IBlobStorageService, IBlobStorageServiceFactory, BlobInformation, BlobInfoType
• Table Storage (→ Akay.To.Azure): ITableStorageRepository, ITableStorageRepositoryFactory, UpdateMode, RowKeyType; TableStorageFilter es un builder concreto implementado en Core
• AI (→ Akay.To.AI): ICognitiveSpeechService, ICognitiveTranslatorService, TranslationResult, TranslationItem

Bootstrap de host

Extensiones para WebApplicationBuilder / IServiceCollection / WebApplication:

• AddConfigurations<TSettings, TValidator>() — bindea, valida y registra settings
• AddBearerOrApiKeyAuthentication() — JWT Bearer, API Key o ambos
• AddCorsOptions(), AddCultureInfo(), AddExceptionHandlerProblemDetails()
• AddHttpApi(), AddHttpInfrastructure(), AddOpenApi()
• AddRateLimitPolicies() — PerUser, PerEndpoint, PerFunction, PerPartitionKey
• AddObservability() — Serilog + OpenTelemetry en un solo método
• ConfigureLaunchUrl(), UseHealthChecksEndpoint()

Registro

var settings = builder.AddConfigurations<ApplicationSettings, ApplicationSettingsValidator>();

builder.Services
    .AddDispatcher(options => { /* habilitar behaviors */ }, typeof(ApplicationRegisterModule).Assembly)
    .AddCache(settings.Cache)
    .AddHttpClients(settings.HttpClientSettings, settings.Application?.Name, settings.Application?.Version)
    .AddUserContext<AkayUserContext>();

Documentación

Consulta docs/ para guías detalladas por funcionalidad (Mediator, Result, Messaging, HybridCache, HttpClient, UserContext, InitialSetup, OpenTelemetry, Serilog).

Changelog

1.1.12

• 2026-09-14
• Normaliza IFormFile en OpenAPI y añade tests de cobertura (fbe1217)

1.1.11

• 2026-09-10
• Reescritura y mejora de documentación técnica (.md) (0f6b5be)

1.1.10

• 2026-09-05
• Añade métodos Remove y RemoveRange a IWriteBaseRepository (5b70f1b)

1.1.9

• 2026-09-03
• Updated README.md (4608042)

1.1.8

• 2026-09-02
• Unifica opciones JSON (95cb451)

1.1.7

• 2026-08-24
• feat(openapi): add stable operation IDs and extension contributors (bc54ccc)

1.1.6

• Añade operation IDs estables y contribuciones OpenAPI extensibles.

1.1.5

• 2026-07-28
• fix(mediator): resolve stream telemetry settings (61ce247)

1.1.4

• 2026-07-28
• feat: IExternalIdentityProvisioningService and IOutboxEventWriter (ac9284b)

1.1.3

• 2026-07-21
• feat: add identity provisioning and reorganize packages by capability (c1ffdaf)

1.1.2

• 2026-07-19
• fix: tests (982c8f5)

1.1.1

• 2026-07-16
• refactor(messaging): extract Rebus provider into Akay.To.Messaging.Rebus (f8f248f)

1.0.3

• 2026-07-14
• Domain events Publish and Handler (0f5752b)

1.0.2

• 2026-07-10
• chore: Versión 1.0.1 (04158e1)
• feat: Add Scalar - Bye bye Swagger 😢 (d364a0c)

0.0.25

• 2026-07-06
• feat: Post devuelve CreatedResponse u objeto enriquecido con Id y CreatedAt. Put devuelve NoContent (64bff39)

0.0.24

• 2026-07-02
• Merge branch 'main' of https://github.com/alvarocaballero/akay-to-core (d554a6e)
• Cambios en paginación y añadido PersistenceResultExecutor y ResultSaveChangesAsync para tratamiento de errores en SaveChangesAsync (da687ee)
• UserContext → clase abstracta y permite Tenant genérico (6dba533)
• Reorder Host Register Extensions (9686584)
• Documentación Tenant → Guid (8dd45c5)

0.0.23

• 2026-06-12
• Merge branch 'feature/akay-to-ef-2' (9f43b07)
• Añadido DbContextSettings a BaseApplicationSettings (08dca6d)
• Añadido ApplicationDbContext y separación de BaseApplicationSettings (e3adbf3)

0.0.22

• 2026-06-11
• Fix tests (e249b9c)

0.0.21

• 2026-06-08
• Merge branch 'main' of https://github.com/alvarocaballero/akay-to-core (aaf65f9)
• Messaging with Rebus (9787bf0)

0.0.20

• 2026-06-05
• Merge branch 'main' of https://github.com/alvarocaballero/akay-to-core (9ebb753)
• Added Unit to Mediator (1cb188d)

0.0.19

• 2026-06-04
• Merge branch 'feature/signalr' (f3815be)
• Added SignalR (3334ac7)

0.0.18

• 2026-06-02
• Merge branch 'feature/azure-tables' (67af22a)
• Interfaces de TableStorage y documentación para Swagger (d90b0bf)

0.0.17

• 2026-05-28
• Merge branch 'feature/cognitive-services' (940d505)
• Name changes in application settings IOptions application HttpClients' resilience depends on having a configuration (443f3b8)
• Name changes in application settings IOptions application HttpClients resilience depends on having a configuration (f7c145d)

0.0.16

• 2026-05-22
• Merge pull request #1 from alvarocaballero/feature/cognitive-services (b878a4e)
• Correcciones (73f3212)
• HttpClientExtensions examples Cognitive Services (e201177)
• Fix configuration (7308c22)
• HttpClientConfiguration & HttpClientExtensions (5000b35)

0.0.15

• 2026-05-19
• Added BlobStorageService and BlobCacheBehavior (f806eef)
• Fix: cache race condition & Create BlobStorageService returns container (9657195)
• Added AzureBlobStorageService (Interface) (e883242)

0.0.14

• 2026-05-13
• Merge branch 'main' of https://github.com/alvarocaballero/akay-to-core (59d4784)
• CompensationContext New CompensationBehavior for ICompensableRequests Generic registration of conditional behaviors: Cache, Retry, Compensation, and Validation Generic registration (once for all) of Logging and Telemetry behaviors (169495e)

0.0.13

• 2026-05-12
• Merge branch 'main' of https://github.com/alvarocaballero/akay-to-core (f88cc8e)
• OpenTelemetry & Serilog (15bf680)
• Mediator & HybridCache (d0231a8)
• Result and UserContext fixed (35102af)

0.0.12

• 2026-05-07
• Result (17bd1dd)

0.0.11

• 2026-05-06
• Merge branch 'main' of https://github.com/alvarocaballero/akay-to-core (a933b81)
• Rate Limit Policies (8f44bb0)
• UserContext (d15b940)
• Added ConfigureLaunchUrl and UseHealthChecksEndpoint WebApplication Extensions (317aca7)
• Added Swagger configuration with accept language. Added IOptions<ApplicationSettings> to DI (e99c669)

0.0.10

• 2026-04-30
• Cambio de nombre de archivo a BaseApplicationSettings (263a065)
• Mejora de validación y reorganización de configuración (c8fa5ec)

0.0.9

• 2026-04-30
• Soporte para autenticación ApiKey y JWT Bearer (c079e0b)

0.0.8

• 2026-04-28
• Merge branch 'main' of https://github.com/alvarocaballero/akay-to-core (4184968)
• fix: join commit array into single string for changelog (235468a)

0.0.7

• 2026-04-28 System.Object[]

0.0.6

• 2026-04-28 System.Object[]

0.0.5

• 2026-04-28 System.Object[]

0.0.4

• 2026-04-28 System.Object[]

0.0.3

• 2026-04-23
• chore: initial application setup
• Eliminada referencia a Microsoft.ApplicationInsights.AspNetCore por vulnerabilidad (8fc1f0b)

0.0.2

• 2026-04-23
• chore: initialize project and release pipeline (b0b0c23)

0.0.1

• 2026-04-17