HerrGeneral.Core 1.7.0

HerrGeneral.Core

Essential components for application integration, mediator dispatch, open pipeline execution, and command concurrency control.

Registration with Dependency Injection

Herr General integrates seamlessly with .NET's dependency injection system using Microsoft.Extensions.DependencyInjection. Configure the framework in your application startup with a fluent API:

// Add Herr General to your service collection
services.AddHerrGeneral(configuration =>
    configuration
        // Register write side assembly and namespace for command and domain event handlers
        .ScanWriteSideOn(typeof(Person).Assembly, typeof(Person).Namespace!)
        // Register in-transaction synchronous projections
        .ScanSyncProjectionsOn(typeof(OrderSummarySyncProjection).Assembly)
        // Register read side assembly for eventual post-transaction projections
        .ScanPostProjectionsOn(typeof(PersonFriendRM).Assembly, typeof(PersonFriendRM).Namespace!)
        // Register post-transaction side effects (emails, notifications, external message bus)
        .ScanSideEffectsOn(typeof(SendWelcomeEmailSideEffect).Assembly));

Pipeline Behaviors & Extension

Modules and consuming applications can intercept command handling by implementing ICommandPipelineBehavior<TCommand, TResult> and optional IOrderedPipelineBehavior:

public class AuditBehavior<TCommand, TResult> : ICommandPipelineBehavior<TCommand, TResult>, IOrderedPipelineBehavior
{
    public PipelinePhase Phase => PipelinePhase.Security;

    public async Task<(IReadOnlyList<object> Events, TResult Result)> HandleAsync(
        CommandExecutionContext<TCommand, TResult> context,
        CommandHandlerDelegate<TResult> next)
    {
        // Custom pre-processing
        var result = await next();
        // Custom post-processing
        return result;
    }
}

This registration process scans the specified assemblies for command handlers, event handlers, projections, and side-effects, registering them with the appropriate lifetime scopes in the dependency injection container.

Handler Taxonomy & Transaction Boundaries

HerrGeneral organizes handler contracts around the IHandle... convention:

1. IHandleSyncProjection<in TEvent>:

   • Executes inside the active IUnitOfWork transaction before Commit().
   • Ideal for strict consistency projections (e.g. SQL read models in the same database) or transactional outbox tables.
   • Throws and triggers RollBack() if an exception occurs.

2. IHandlePostProjection<in TEvent>:

   • Executes strictly after IUnitOfWork.Commit() succeeds.
   • Ideal for eventual consistency projections and search indexes.
   • Exceptions are captured by CommandExecutionTracer and logged without affecting the committed transaction.

3. IHandleSideEffect<in TEvent>:

   • Executes strictly after IUnitOfWork.Commit() succeeds.
   • Ideal for fire-and-forget side effects, emails, external webhooks, and message publishing.
   • Exceptions are captured and isolated by CommandExecutionTracer.

Mediator

Send your commands with the mediator:

var mediator = serviceProvider.GetRequiredService<Mediator>();
var result = await mediator.Send(new MyCommand());

Command Concurrency & Partition-Based Locking

HerrGeneral features a built-in CommandConcurrencyLimiter that ensures commands targeting the same aggregate or partition are serialized while allowing independent aggregates to execute concurrently.

Declarative Attribute Locking (Recommended)

Decorate the identifier property of your command with [LockKey<TAggregate>] (or [LockKey(typeof(TAggregate))]):

using HerrGeneral.WriteSide;

public record CancelOrder(
    [property: LockKey<Order>] Guid OrderId, 
    string Reason
);

Commands with the same (typeof(Order), OrderId) lock key are processed sequentially. Commands with different IDs or different aggregate types execute concurrently.

Interface-Based Locking (Extension Point)

For complex, dynamic, or composite partition keys, implement IKeyedCommand:

using HerrGeneral.WriteSide;

public record ProcessPayment(Guid TenantId, Guid AccountId, decimal Amount) : IKeyedCommand
{
    public object Key => (TenantId, typeof(Account), AccountId);
}

External Handler Integration

Herr General provides a comprehensive set of configuration methods to integrate existing handlers or third-party components that don't follow the standard conventions. This flexibility is essential when working with legacy systems or external libraries.

Command Handler Integration Methods

The Configuration class offers several methods to adapt different types of external command handlers:

1. Simple Command Handler Registration

For handlers that already return events in the expected format (IEnumerable<object>):

services.UseHerrGeneral(config => 
    config.MapCommandHandler<MyCommand, ExternalCommandHandler>());

How it works:

• Registers ExternalCommandHandler as the handler for MyCommand
• The handler's return value is used directly as the event collection
• Suitable for handlers that already return a collection of events

2. Command Handler with Event Mapping

For handlers that return a custom result type that needs transformation:

services.UseHerrGeneral(config => 
    config.MapCommandHandler<MyCommand, ExternalCommandHandler, CustomResult>(
        // Transform function: converts the handler result into events
        result => result.MyEvents
    ));

How it works:

• The handler returns a custom type (CustomResult)
• The provided mapping function transforms this result into a collection of events
• Enables integration with handlers that don't directly produce events

3. Command Handler with Value Return

For handlers that need to produce both events and a specific return value (especially useful for creation commands):

services.UseHerrGeneral(config => 
    config.MapCommandHandler<CreateEntity, ExternalCreateHandler, CustomResult, Guid>(
        // Event mapping function
        result => result.MyEvents,
        
        // Value mapping function
        result => result.Id // Returns the ID to the caller
    ));

How it works:

• The first function maps the handler result to domain events
• The second function extracts a specific value from the result to return to the caller
• Perfect for creation commands where you need to return the new entity's ID
• The extracted value is wrapped in a Result<TValue> for consistent error handling

Event Handler Integration

Event handlers can also be externally registered for both write and read sides:

Write Side Event Handlers

services.UseHerrGeneral(config =>
    config.MapEventHandlerOnWriteSide<PaymentReceived, UpdateAccountBalanceHandler>());

Purpose: Register handlers that perform domain logic in response to events (may generate additional events).

Read Side Event Handlers

services.UseHerrGeneral(config =>
    config.MapEventHandlerOnReadSide<OrderShipped, UpdateShippingStatisticsHandler>());

Purpose: Register handlers that update read models and projections (should not produce new events).

Domain Exception Registration

Herr General distinguishes between technical failures and business rule violations by registering domain exceptions:

services.UseHerrGeneral(config =>
    config.UseDomainException<InsufficientFundsException>());

Benefits:

• Registered exceptions are treated as expected business outcomes rather than system errors
• They are automatically wrapped in a DomainError result instead of an Exception result
• Provides a cleaner separation between technical failures and business rule violations

Diagnostic Logging & Causal Tree Tracing

HerrGeneral includes a structured causal tree formatter (ActivityTreeFormatter) that logs the hierarchical execution path of every command when logging is enabled (LogLevel.Information or LogLevel.Debug):

CMD [ProcessCardPayment] (thread #12) ............................. [OK] (16.2ms)
 |
 \--> (cmd) ProcessCardPaymentHandler (0.8ms)
       |
       |-- (evt) CardPaymentAuthorized
       |    \--> (wr) DebitAccountOnCardPayment (2.3ms)
       |          \-- (evt) AccountDebited
       |               \--> (wr) ApplyOverdraftFeeOnAccountDebited (1.4ms)
       |                     \-- (evt) FeeApplied
       |
       \== [TX COMMIT] (1.1ms)
       |
       +-- [SYNC PROJECTIONS] (Read-Side)
       |    |-- CardPaymentAuthorized        ===> CardTransactionsView         (1.8ms)
       |    |-- AccountDebited               ===> AccountBalanceView           (2.1ms)
       |    \-- FeeApplied                   ===> AccountStatementView         (1.2ms)
       |
       \-- [POST TRANSACTION] (Side Effects & Outbox)
            |-- CardPaymentAuthorized        ===> SendSmsConfirmation          (2.4ms)
            \-- FeeApplied                   ===> SendOverdraftWarning         (2.0ms)