DRN.Framework.SharedKernel 0.7.0-preview059

DRN.Framework.SharedKernel

Lightweight package containing domain primitives, exceptions, and shared code suitable for Contract and Domain layers.

TL;DR

• Zero dependencies - Safe for Contract/Domain layers without framework overhead
• Domain primitives - SourceKnownEntity, AggregateRoot, DomainEvent for DDD patterns
• Type-safe exceptions - ExceptionFor.NotFound(), ExceptionFor.Validation() map to HTTP status codes
• JSON conventions - Global System.Text.Json defaults with camelCase, enums-as-strings
• Source Known IDs - Internal long for DB performance, external Guid for API security

Table of Contents

• QuickStart: Beginner
• QuickStart: Advanced
• Domain Primitives
• SourceKnownRepository
• Pagination
• Exceptions
• JsonConventions
• Attributes
• AppConstants

QuickStart: Beginner

Define your first domain entity with automatic ID generation and domain events:

using DRN.Framework.SharedKernel.Domain;

[EntityType(1)] // Unique byte identifier for this entity type
public class User : AggregateRoot
{
    public string Name { get; private set; }

    public User(string name)
    {
        Name = name;
        AddDomainEvent(new UserCreated(this)); // Automatically published by DrnContext
    }
}

public class UserCreated(User user) : EntityCreated(user)
{
    public string UserName => user.Name;
}

QuickStart: Advanced

Complete example with pagination, validation, and exception handling:

// Repository usage with pagination
public class UserService(ISourceKnownRepository<User> repository)
{
    public async Task<PaginationResultModel<UserDto>> GetUsersAsync(PaginationRequest request)
    {
        // Cursor-based pagination with date filtering
        var filter = EntityCreatedFilter.After(DateTimeOffset.UtcNow.AddDays(-30));
        var result = await repository.PaginateAsync(request, filter);
        
        return result.ToModel(user => new UserDto
        {
            Id = user.EntityId,  // External GUID for API
            Name = user.Name
        });
    }

    public async Task<User> GetUserAsync(Guid id)
    {
        var user = await repository.GetOrDefaultAsync(id);
        if (user is null)
            throw ExceptionFor.NotFound($"User {id} not found"); // Maps to HTTP 404
        
        return user;
    }
}

Domain Primitives

Following definitions provide guidance and conventions for rapid and effective domain design. Their usage is optional but highly recommended for compatibility with DrnContext features.

Entity and AggregateRoot

• SourceKnownEntity: The base class for all entities. Handles identity (long Id internal, Guid EntityId external), domain events, and auditing.
• AggregateRoot: Marker class for DDD aggregate roots.
• [EntityType(byte)]: Attribute defining a stable, unique byte identifier for each entity type. Required for ID generation and DrnContext startup validation.

using DRN.Framework.SharedKernel.Domain;

[EntityType(1)] // Mandatory: Unique byte identifier for this entity type
public class User : AggregateRoot 
{
    public string Name { get; private set; }

    public User(string name) 
    {
        Name = name;
        AddDomainEvent(new UserCreated(this)); // Auto-published by DrnContext
    }
}

Domain Events

Entities encapsulate their events. DrnContext publishes them automatically upon saving changes.

public class UserCreated(User user) : EntityCreated(user)
{
    public string UserName => user.Name;
}

public interface IDomainEvent
{
    Guid Id { get; }
    DateTimeOffset Date { get; }
    Guid EntityId { get; }
}

public abstract class DomainEvent(SourceKnownEntity sourceKnownEntity) : IDomainEvent
{
    public Guid Id { get; protected init; } = Guid.NewGuid();
    public Guid EntityId => sourceKnownEntity.EntityId;
    public DateTimeOffset Date { get; protected init; } = DateTimeOffset.UtcNow;
}

public abstract class EntityCreated(SourceKnownEntity sourceKnownEntity) : DomainEvent(sourceKnownEntity);
public abstract class EntityModified(SourceKnownEntity sourceKnownEntity) : DomainEvent(sourceKnownEntity);
public abstract class EntityDeleted(SourceKnownEntity sourceKnownEntity) : DomainEvent(sourceKnownEntity);

SourceKnownEntityId & SourceKnownId

The framework uses a Source Known identifier system (SourceKnownEntityId) to balance database performance (long) with external security (Guid) and type safety.

// entityId.Valid will be true only if the GUID structure is correct AND matches the User entity type.
var entityId = user.GetEntityId(someGuid, validate: true);

ID Validation & Retrieval Strategies

The framework provides three distinct ways to validate and retrieve typed identifiers based on the operational context:

1. Injectable Utility (Recommended for Service Layer)

Ideal for cross-cutting business logic or when you have the sourceKnownEntityIdUtils in scope.

var id = sourceKnownEntityIdUtils.Validate<User>(externalGuid);

2. Repository (Recommended for Data Access)

Directly available on ISourceKnownRepository<TEntity>. Standardizes validation at the data entry point.

var id = userRepository.GetEntityId(externalGuid); 

3. Domain Entity (Recommended for Domain Logic)

Uses helper methods on the SourceKnownEntity base class. Best for intra-domain operations.

var id = userInstance.GetEntityId<User>(externalGuid);

namespace DRN.Framework.SharedKernel.Domain;

/// <summary>
/// Application wide Unique Entity Type
/// </summary>
[AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
public sealed class EntityTypeAttribute(byte entityType) : Attribute
{
    public byte EntityType { get; } = entityType;
}

public abstract class SourceKnownEntity(long id = 0) : IHasEntityId, IEquatable<SourceKnownEntity>, IComparable<SourceKnownEntity>
{
    public const int IdColumnOrder = 0;
    public const int ModifiedAtColumnOrder = 1;

    // ... Internal implementation omitted for brevity ...

    /// <summary>
    /// Internal use only, Use EntityId for external usage
    /// </summary>
    [JsonIgnore]
    [Column(Order = IdColumnOrder)]
    public long Id { get; internal set; } = id;

    /// <summary>
    /// External use only, don't use Id for external usage
    /// </summary>
    [JsonPropertyName(nameof(Id))]
    public Guid EntityId => EntityIdSource.EntityId;

    public DateTimeOffset CreatedAt => EntityIdSource.Source.CreatedAt;

    [ConcurrencyCheck]
    public DateTimeOffset ModifiedAt { get; protected internal set; }

    [JsonIgnore]
    public SourceKnownEntityId EntityIdSource { get; internal set; }
    
    // ... GetEntityId methods ...
}

public abstract class AggregateRoot(long id = 0) : SourceKnownEntity(id);

public abstract class AggregateRoot<TModel>(long id = 0) : AggregateRoot(id), IEntityWithModel<TModel> where TModel : class
{
    public TModel Model { get; set; } = null!;
}

public readonly record struct SourceKnownId(
    long Id,                // The internal database ID (64-bit integer)
    DateTimeOffset CreatedAt, // Timestamp when the ID was generated
    uint InstanceId,        // Generator instance ID (for distributed uniqueness)
    byte AppId,             // Application ID
    byte AppInstanceId      // Application Instance ID
);

public readonly record struct SourceKnownEntityId(
    SourceKnownId Source,   // The decoded internal components
    Guid EntityId,          // The external opaque GUID
    byte EntityType,        // The entity type identifier (from EntityTypeAttribute)
    bool Valid              // Whether the ID structure is valid
)
{
    // Validates that this ID belongs to the specified TEntity type
    public void Validate<TEntity>() where TEntity : SourceKnownEntity 
        => Validate(SourceKnownEntity.GetEntityType<TEntity>());
        
    // Validates ID structure and checks type match
    public void Validate(byte entityType);
}

SourceKnownRepository

ISourceKnownRepository<TEntity> defines a standard contract for repositories managing AggregateRoot entities.

• Standardized Access: Provides common CRUD operations (CreateAsync, GetAsync, DeleteAsync).
• Identity Conversion: Includes methods to convert between external Guids and internal SourceKnownEntityIds ensuring IDs are valid.
• Cancellation Support: Built-in support for CancellationToken propagation and merging.
• Streaming: Supports IAsyncEnumerable for processing large datasets efficiently.

public interface ISourceKnownRepository<TEntity> where TEntity : AggregateRoot
{
    RepositorySettings<TEntity> Settings { get; set; }
    CancellationToken CancellationToken { get; set; }
    
    // Identity Conversion & Validation
    SourceKnownEntityId GetEntityId(Guid id, bool validate = true);
    SourceKnownEntityId GetEntityId<TOtherEntity>(Guid id) where TOtherEntity : SourceKnownEntity;
    
    // Data Access
    Task<TEntity> GetAsync(Guid id);
    Task<TEntity?> GetOrDefaultAsync(SourceKnownEntityId id, bool validate = true);
    
    // Batch & Counts
    Task<bool> AnyAsync(Expression<Func<TEntity, bool>>? predicate = null);
    Task<long> CountAsync(Expression<Func<TEntity, bool>>? predicate = null);
    
    // Modification
    void Add(params IReadOnlyCollection<TEntity> entities);
    void Remove(params IReadOnlyCollection<TEntity> entities);
    Task<int> SaveChangesAsync();
    
    // Pagination & Streaming
    Task<PaginationResultModel<TEntity>> PaginateAsync(PaginationRequest request, EntityCreatedFilter? filter = null);
    IAsyncEnumerable<PaginationResultModel<TEntity>> PaginateAllAsync(PaginationRequest request, EntityCreatedFilter? filter = null);
    
    // Dangerous
    Task<TEntity[]> GetAllAsync();
}

Filtering

EntityCreatedFilter provides standardized date-based filtering, useful for time-series data or audit logs.

// Example: Get records created in the last 7 days
var filter = EntityCreatedFilter.After(DateTimeOffset.UtcNow.AddDays(-7));
var result = await repository.PaginateAsync(request, filter);

Pagination

The framework provides a robust cursor-based pagination system to balance performance and usability.

API Integration

PaginationRequest is natively URL-serializable. In Controllers, simply bind it from the query string.

[HttpGet]
public async Task<PaginationResultModel<UserDto>> GetAsync([FromQuery] PaginationRequest request)
{
    var result = await repository.PaginateAsync(request);
    return result.ToModel(user => user.ToDto());
}

Usage

// Example usage in a repository or service
var request = PaginationRequest.DefaultWith(size: 20, direction: PageSortDirection.Descending);
var result = await repository.PaginateAsync(request);

if (result.Info.HasNext) 
{
    // Use result.Info.RequestNextPage() for the next link
}

Exceptions

DrnException types map automatically to HTTP status codes via the ExceptionFor factory.

namespace DRN.Framework.SharedKernel;

/// <summary>
/// DrnExceptions are handled by scope handler and can be used to short circuit the processing pipeline
/// </summary>
public abstract class DrnException(string message, Exception? ex, string? category, short? status = null)
    : Exception(message, ex)
{
    public const string DefaultCategory = "default";
    public string Category { get; } = category ?? DefaultCategory;
    public short Status { get; } = status ?? 500;
}

public static class ExceptionFor
{
    private const string Default = DrnException.DefaultCategory;

    public static ValidationException Validation(string message, Exception exception = null!, string? category = Default)
        => new(message, exception, category);
        
    public static NotFoundException NotFound(string message, Exception exception = null!, string? category = Default)
        => new(message, exception, category);
        
    // ... other factory methods ...
}

JsonConventions

JsonConventions globally overrides System.Text.Json settings. These are automatically applied by DrnTestContext (in tests) and DrnHostBuilder (in hosted apps).

Applied Settings:

• JsonSerializerDefaults.Web (CamelCase naming, case-insensitive)
• JsonStringEnumConverter (Enums as strings)
• AllowTrailingCommas = true
• NumberHandling = AllowReadingFromString

namespace DRN.Framework.SharedKernel.Json;

public static class JsonConventions
{
    static JsonConventions()
    {
        UpdateDefaultJsonSerializerOptions();
    }

    public static readonly JsonSerializerOptions DefaultOptions = SetJsonDefaults();

    public static JsonSerializerOptions SetJsonDefaults(JsonSerializerOptions? options = null)
    {
        options ??= new JsonSerializerOptions(JsonSerializerDefaults.Web);

        options.Converters.Add(new JsonStringEnumConverter());
        options.Converters.Add(new Int64ToStringConverter());
        options.Converters.Add(new Int64NullableToStringConverter());
        options.AllowTrailingCommas = true;
        options.PropertyNameCaseInsensitive = true;
        options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        options.NumberHandling = JsonNumberHandling.AllowReadingFromString;
        options.MaxDepth = 32;
        // ...
        return options;
    }
}

Attributes

[IgnoreLog]

Excludes sensitive properties or entire classes from scoped logging.

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Property | AttributeTargets.Field)]
public class IgnoreLogAttribute : Attribute;

[SecureKey]

Validates that a string meets secure key requirements (length, character classes).

AppConstants

namespace DRN.Framework.SharedKernel;

public static class AppConstants
{
    public static int ProcessId { get; } = Environment.ProcessId;
    public static Guid AppInstanceId { get; } = Guid.NewGuid();
    public static string EntryAssemblyName { get; } = Assembly.GetEntryAssembly()?.GetName().Name ?? "Entry Assembly Not Found";
    public static string TempPath { get; } = GetTempPath(); //Cleans directory at every startup
    public static string LocalIpAddress { get; } = GetLocalIpAddress();
}

Semper Progressivus: Always Progressive

Commit Info

Author: Duran Serkan KILIÇ
Date: 2026-01-26 21:12:39 +0300
Hash: 858b6f431aa962dcd742ffa77fa3a94322c3754e