Vuresoft.Events 0.1.2

Vuresoft.Events

A lightweight, channel-based event processing library for .NET 9+ applications. Provides reliable event publishing, handling, and persistence with correlation tracking.

Features

• Channel-based Processing: Uses unbounded channels for async event processing
• Event Persistence: Automatic event storage with JSON serialization and correlation IDs
• Type Safety: Strongly-typed event handlers with compile-time validation
• Correlation Tracking: Correlation ID support for distributed tracing
• Pluggable Persistence: Support for custom persistence providers

Installation

dotnet add package Vuresoft.Events

Quick Start

1. Define Your Events

public record PatientRegisteredEvent(string PatientId, string CorrelationId) : EventBase(CorrelationId);

public record AppointmentScheduledEvent(string AppointmentId, DateTime ScheduledDate, string CorrelationId) : EventBase(CorrelationId);

2. Configure Services in Startup

For Testing (In-Memory)

public void ConfigureServices(IServiceCollection services)
{
    // Add event manager with in-memory persistence
    services.AddEventsManagerInMemoryOnly();
}

For Production (Custom Persistence)

public void ConfigureServices(IServiceCollection services)
{
    // Add event manager with custom persistence (e.g., Entity Framework)
   // registered manually
     services.AddSingleton<SaveEventDelegate>(provider => async (eventData, cancellationToken) =>
        {
            var scopeFactory = provider.GetRequiredService<IServiceScopeFactory>();
            using var scope = scopeFactory.CreateScope();
            var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();

            var eventStore = new EventStore(eventData);
            dbContext.EventStore.Add(eventStore);
            await dbContext.SaveChangesAsync(cancellationToken);
        });
        services.AddEventsManager();
            
        // Or use Fluent method on eventsManager.    
        services.AddEventsManager()
            .WithSaveDelegate(provider => async (eventData, cancellationToken) =>
        {
            var scopeFactory = provider.GetRequiredService<IServiceScopeFactory>();
            using var scope = scopeFactory.CreateScope();
            var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();

            var eventStore = new EventStore(eventData);
            dbContext.EventStore.Add(eventStore);
            await dbContext.SaveChangesAsync(cancellationToken);
        });
}

3. Register Event Handlers

Create a mapping class for setting handlesr for each event

public class EventMappings(
    IOptions<SystemConfig> systemConfig,
    EventManager eventManager,
    IServiceScopeFactory serviceScopeFactory)

{
    public void SetEventHandlers()
    {
        eventManager.On<OrderCreatedOrUpdated>(async data =>
        {
            await using var scope = serviceScopeFactory.CreateAsyncScope();
            var orderProcessor =
                scope.ServiceProvider.GetRequiredService<OrderProcessor>();
            await orderProcessor
                .AddOrder(data.OrderId, CancellationToken.None).ConfigureAwait(false);
        });

4. Publish Events

[ApiController]
public class OrderController : ControllerBase
{
    private readonly EventManager _eventManager;

    public OrderController(EventManager eventManager)
    {
        _eventManager = eventManager;
    }

    [HttpPost]
    public async Task<IActionResult> CreateOrder(RegisterOrderRequest request)
    {
        var correlationId = HttpContext.TraceIdentifier;
        
        // Create Order
        
        // Publish event - will be processed asynchronously
        _eventManager.PublishEvent(new OrderCreatedOrUpdated(order.OrderId, correlationId));
        
        return Ok;
    }
}

Performance Considerations

• Events are processed asynchronously without blocking the publisher
• Failed events are logged but don't retry automatically
• Event persistence happens before handler execution for reliability
• Unbounded channels can grow large under high load - monitor memory usage