Genocs.Common Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.Common Agent Reference

Purpose

This document is optimized for AI-assisted development sessions. It prioritizes fast retrieval of:

  • What Genocs.Common is responsible for
  • Which abstractions to implement for specific goals
  • Where source of truth lives for each primitive
  • What constraints and runtime behaviors matter

Quick Facts

KeyValue
PackageGenocs.Common
Project filesrc/Genocs.Common/Genocs.Common.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleShared primitives, CQRS contracts, domain model abstractions, and cross-cutting utility types for all Genocs packages
Core themesCQRS interfaces, domain-driven design building blocks, paged query support, notification model, DI markers, persistence initialization

Use This Package When

  • Defining commands, queries, or events that flow through the Genocs pipeline
  • Modeling domain entities and aggregate roots with a primary key
  • Implementing a repository abstraction supporting LINQ queries and async operations
  • Building paged query responses consumed by WebApi endpoints
  • Marking services for DI lifetime conventions (ISingletonDependency, ITransientDependency)
  • Wiring up database seeders and initializers via IDatabaseInitializer
  • Publishing or handling in-app notifications (INotificationMessage, BasicNotification)

Do Not Assume

  • This package has no runtime dependencies — it is pure abstractions and lightweight primitives; no framework services are registered automatically
  • DefaultIdType is a global alias for System.Guid defined in Directory.Build.props; do not use raw Guid in entity primary keys
  • ICommand, IQuery, IEvent carry no data by themselves; concrete command/query classes implement these interfaces and add their own properties

High-Value Entry Points

CQRS Contracts

Query & Paging Contracts

Domain Model Abstractions

Repository & Persistence Abstractions

Cross-Cutting Service Interfaces

Type Attributes & Utilities

Notifications & Configuration

Decision Matrix For Agents

GoalPreferred APINotes
Define a commandImplement ICommandAdd your data properties on the concrete class
Define a query returning a pageImplement IPagedQuery; return PagedResult<T>Use PagedQueryBase for base implementation with Page, Results, OrderBy, SortOrder
Define an eventImplement IEventFor rejected/failure events, also implement IRejectedEvent
Define a domain entityImplement IEntity<TKey> using DefaultIdType as TKeyUse IAggregateRoot<TKey> for roots that generate domain events
Implement a repositoryExtend IRepositoryOfEntity<TEntity, TKey>Full LINQ + async query surface
Map a message to a queueApply [Message(exchange, queue)] to command/event classUsed by Genocs.Messaging.RabbitMQ to resolve routing
Tag a class as decoratorApply [Decorator] attributeScrutor-based decorator discovery uses this marker
Access the current userResolve ICurrentUserExposes GetUserId(), GetUserEmail(), GetTenant(), IsInRole(), GetUserClaims()
Seed a database at startupImplement ICustomSeeder and IDatabaseInitializerWire via DI; call InitializeDatabasesAsync() in hosted startup

Minimal Integration Recipe

Install 

dotnet add package Genocs.Common

Usage Example

Genocs.Common contains only interfaces and primitives — no Program.cs wiring is required. Usage is purely by implementing the provided interfaces:

using Genocs.Common.CQRS.Commands;
using Genocs.Common.CQRS.Queries;
using Genocs.Common.Domain.Entities;
using Genocs.Common.Types;

// Define a command
public record CreateOrderCommand(DefaultIdType CustomerId, decimal Amount) : ICommand;

// Define a command handler
public class CreateOrderHandler : ICommandHandler<CreateOrderCommand>
{
    public async Task HandleAsync(CreateOrderCommand command, CancellationToken cancellationToken = default)
    {
        // business logic
    }
}

// Define a paged query
public class GetOrdersQuery : PagedQueryBase, IPagedQuery
{
    public string? CustomerId { get; set; }
}

// Define a paged result usage
var result = PagedResult<OrderDto>.Create(items, page, pageSize, totalPages, totalCount);

// Domain entity
public class Order : IEntity<DefaultIdType>
{
    public DefaultIdType Id { get; set; }
    public bool IsTransient() => Id == DefaultIdType.Empty;
}

// Message routing attribute for RabbitMQ
[Message(exchange: "orders", queue: "orders.create")]
public record CreateOrderCommand(...) : ICommand;

Behavior Notes That Affect Agent Decisions

  • DefaultIdType is a global using alias for System.Guid, set in Directory.Build.props; always use DefaultIdType in entity primary keys to stay consistent with the codebase convention
  • PagedResult<T>.Create(...) is the canonical factory; never construct PagedResult<T> via its constructor directly from external code since its constructors are protected
  • IAggregateRoot<TKey> exposes List<IEvent>? DomainEvents for domain event collection; implementations must populate this list and clear it after publishing
  • [MessageAttribute] on a command or event class is the sole source of messaging routing metadata consumed by Genocs.Messaging.RabbitMQ; ensure exchange and queue values match infrastructure configuration
  • ICurrentUser is a cross-cutting interface — concrete implementations are provided by Genocs.Auth and resolved via DI; do not instantiate directly
  • IDatabaseInitializer.InitializeDatabasesAsync() is not called automatically — the host application must invoke it at startup
  • IPagedQuery uses zero-based page indexing (Page starts at 0)

Source-Accurate Capability Map

CQRS Message Contracts

  • ICommand — marker for write-side commands
  • ICommandHandler<TCommand> — single-method HandleAsync(TCommand, CancellationToken) contract
  • ICommandDispatcher — dispatches commands to their registered handlers
  • IMessage — root marker for commands and events (via IDispatcher)

Files:

Event Contracts

  • IEvent — marker for integration and domain events
  • IEventHandler<TEvent> — single-method HandleAsync(TEvent, CancellationToken) contract
  • IRejectedEvent / RejectedEvent — rejection event with Code and Reason properties
  • IEventDispatcher — dispatches events to their registered handlers

Files:

Paged Query Support

  • IPagedQuery — Page, Results, OrderBy, SortOrder properties
  • PagedQueryBase — base class implementing IPagedQuery
  • PagedQueryWithFilter — extends PagedQueryBase with a filter bag
  • PagedResult<T> — carries Items collection plus pagination metadata; factory: PagedResult<T>.Create(...) and PagedResult<T>.From(...)
  • SearchRequest — text search + paging in one object

Files:

Domain Model Abstractions

  • IEntity / IEntity<TKey> — base entity with transient check
  • IAggregateRoot<TKey> — extends entity with List<IEvent>? DomainEvents for domain event tracking
  • ISoftDelete — IsDeleted / DeletedOn convention marker
  • Auditing interfaces in Auditing/ — created/modified tracking

Files:

Repository & Persistence Contracts

  • IRepositoryOfEntity<TEntity, TKey> — full LINQ + async CRUD surface: GetAll(), GetAllList(), GetAllListAsync(), GetAllIncluding(...), filter overloads
  • IUnitOfWork — transaction boundary marker
  • IDatabaseInitializer — InitializeDatabasesAsync() for startup
  • ICustomSeeder — implements custom per-table/collection seeding logic

Files:

Cross-Cutting Interfaces

  • ICurrentUser — GetUserId(), GetUserEmail(), GetTenant(), IsAuthenticated(), IsInRole(role), GetUserClaims()
  • IDto — marker for data transfer objects
  • ISerializerService — serialize/deserialize abstraction
  • INotificationSender — pushes INotificationMessage to consumers
  • ISingletonDependency / ITransientDependency — DI lifetime convention markers for auto-registration

Files:

Type Attributes & Utilities

  • [Message(exchange, topic, queue, queueType, errorQueue, subscriptionId)] — routing metadata for messaging infrastructure
  • [Decorator] — marks a class as an injected decorator (used by Scrutor-based wiring)
  • [HiddenAttribute] / [PublicContractAttribute] — visibility control for published contracts
  • GetDefaultInstance(this Type) / SetDefaultInstanceProperties(this object) — reflection-based default value helpers

Files:

Dependencies

From src/Genocs.Common/Genocs.Common.csproj:

  • No external NuGet dependencies — this is a zero-dependency primitives package
  • Targets: net10.0, net9.0, net8.0
Last modified on March 21, 2026
Edit this page on GitHub
← Genocs.Auth Agent Reference
Genocs.Common Library →