Nera.Lib.Messaging.Abstractions 2.0.2

Nera.Lib.Messaging.Abstractions

Version: 1.0.0
Framework: .NET 9.0
Transport: RabbitMQ via MassTransit 8.5.2

Overview

A comprehensive messaging abstraction library for building event-driven microservices with clear separation between in-service domain events and cross-service integration events.

Key Features

• Simple like MediatR - Familiar API for developers
• Auto-discovery - Automatic handler registration
• Proper lifetimes - Correct DI scoping
• Error isolation - One failing handler won't crash others
• Zero configuration - Works out of the box with environment variables
• Type-safe - Full compile-time type checking
• Centralized Configuration - All RabbitMQ settings from NeraBaseConfiguration

Quick Start

1. Install Package

<PackageReference Include="Nera.Lib.Messaging.Abstractions" Version="1.0.0" />

2. Register Services

// Program.cs or Startup.cs
services.AddNeraMessaging(NeraConfiguration.Instance.Configuration, builder => builder
    .WithServiceName("my-service")
    .UseInServiceEvents()
    .UseIntegrationEvents()
    .UseMessageContext()
    .UseTracing()
    .Build());

3. Define Events

// In-Service Event (Domain Event)
public class UserCreatedEvent : IInServiceEvent
{
    public Guid UserId { get; set; }
    public string Email { get; set; } = string.Empty;
}

// Integration Event (Cross-Service)
public record UserCreatedIntegrationEvent : IntegrationMessageBase
{
    public Guid UserId { get; init; }
    public string Email { get; init; } = string.Empty;
}

4. Create Handlers

// In-Service Event Handler
public class SendWelcomeEmailHandler : IInServiceEventHandler<UserCreatedEvent>
{
    public async Task Handle(UserCreatedEvent @event, CancellationToken cancellationToken)
    {
        await SendWelcomeEmail(@event.Email);
    }
}

5. Publish Events

public class UserService
{
    private readonly IInServiceEventBus _inServiceEventBus;
    private readonly IIntegrationEventPublisher _integrationEventPublisher;

    public async Task CreateUserAsync(CreateUserRequest request)
    {
        var user = await CreateUserLogic(request);
        
        // Publish in-service event
        await _inServiceEventBus.Publish(new UserCreatedEvent 
        { 
            UserId = user.Id, 
            Email = user.Email 
        });
        
        // Publish integration event (to other services)
        await _integrationEventPublisher.PublishAsync(new UserCreatedIntegrationEvent
        {
            UserId = user.Id,
            Email = user.Email
        });
    }
}

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Your Service                                 │
├─────────────────────────────────────────────────────────────────┤
│  In-Service Events (Fast, Same Process)                        │
│  ┌─────────────┐    ┌─────────────────────────────────────┐     │
│  │  Publisher  │───▶│  IInServiceEventBus                 │     │
│  └─────────────┘    │  ├─ Handler 1                       │     │
│                     │  ├─ Handler 2                       │     │
│                     │  └─ Handler N                       │     │
│                     └─────────────────────────────────────┘     │
├─────────────────────────────────────────────────────────────────┤
│  Integration Events (Reliable, Cross-Service)                  │
│  ┌─────────────┐    ┌─────────────────────────────────────┐     │
│  │  Publisher  │───▶│  MassTransit + RabbitMQ             │     │
│  └─────────────┘    └─────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘

Folder Structure

Nera.Lib.Messaging.Abstractions/
├── Abstractions/                 # Core interfaces
│   ├── IEventBus.cs              # Cross-service event publishing
│   ├── ICommandBus.cs            # Command sending
│   └── IMessageContextAccessor.cs# Context (TenantId, UserId, etc.)
│
├── Builders/                     # Configuration builders
│   ├── MessagingBuilder.cs       # Fluent API builder
│   └── MessagingOptions.cs       # All configuration options
│
├── Configuration/                # Setup & registration
│   ├── MessageHeaders.cs         # Standard header names
│   └── ServiceCollectionExtensions.cs
│
├── Events/                       # Event types
│   ├── IInServiceEvent.cs        # In-service event marker
│   ├── IInServiceEventBus.cs     # In-service event bus
│   ├── InServiceEventBus.cs      # Implementation
│   ├── IIntegrationMessage.cs    # Integration event base
│   └── IIntegrationEventPublisher.cs
│
├── Extensions/                   # Extension methods
│   ├── MessagingBuilderExtensions.cs
│   └── ServiceCollectionExtensions.cs
│
├── Implementation/               # Core implementations
│   └── InServiceEventExtensions.cs
│
└── MassTransit/                  # MassTransit implementations
    ├── Consumers/
    │   └── ConsumerBase.cs
    └── Implementation/
        ├── MassTransitEventBus.cs
        └── MassTransitIntegrationEventPublisher.cs

Configuration

RabbitMQ Options

services.AddNeraMessaging(options =>
{
    options.ServiceName = "my-service";
    
    // RabbitMQ settings (auto-loaded from environment)
    options.RabbitMq = new RabbitMqOptions
    {
        Host = "localhost",
        Port = 5672,
        Username = "guest",
        Password = "guest",
        VirtualHost = "/",
        ExchangeName = "nera_exchange",
        QueueName = "nera_queue",
        RoutingKey = "nera_routing_key"
    };
});

Environment Variables

# RabbitMQ Connection
ENV_RABBITMQ_CONNECTION_STRING=amqp://guest:guest@localhost:5672
ENV_RABBIT_MQ_PORT=5672
ENV_RABBIT_MQ_USERNAME=guest
ENV_RABBIT_MQ_PASSWORD=guest
ENV_RABBIT_MQ_VIRTUAL_HOST=/

# RabbitMQ Messaging
ENV_RABBITMQ_EXCHANGE_NAME=nera_exchange
ENV_RABBITMQ_QUEUE_NAME=nera_queue
ENV_RABBITMQ_ROUTING_KEY=nera_routing_key

Custom Consumer Endpoints

services.AddNeraMessaging(options =>
{
    options.ServiceName = "scheduler-service";
    
    // Add custom consumer endpoint
    options.ConsumerEndpoints.Add(new ConsumerEndpointConfig
    {
        EndpointName = "my-custom-queue",
        ConsumerType = typeof(MyConsumer),
        RetryIntervals = new[]
        {
            TimeSpan.FromSeconds(1),
            TimeSpan.FromSeconds(5),
            TimeSpan.FromSeconds(15)
        },
        PrefetchCount = 16
    });
    
    // Register consumer
    options.ConfigureBus = x => x.AddConsumer<MyConsumer>();
});

Fluent Builder API

services.AddNeraMessaging(configuration, builder => builder
    // Core
    .WithServiceName("my-service")
    
    // In-Service Events
    .UseInServiceEvents()
    .UseAsyncEventHandling()
    .UseParallelEventHandling(maxConcurrent: 10)
    
    // Integration Events
    .UseIntegrationEvents()
    .UseOutboxPattern()
    .UseIdempotency()
    .UseDeadLetterQueue()
    
    // Message Context
    .UseMessageContext()
    .UseCorrelationId()
    .UseMultiTenancy()
    
    // Observability
    .UseTracing()
    .UseDistributedTracing()
    .UseMetrics()
    
    // Error Handling
    .UseCircuitBreaker()
    .UseValidation()
    
    // Handlers
    .AddEventHandlerAssemblies(assemblies)
    .AddConsumerAssemblies(assemblies)
    
    // Build
    .Build());

Message Headers

All messages are automatically enriched with standard headers:

Event Types Comparison

Best Practices

✅ DO

// Use centralized AddNeraMessaging
services.AddNeraMessaging(configuration, builder => builder
    .WithServiceName("my-service")
    .Build());

// Use ConsumerEndpointConfig for custom queues
options.ConsumerEndpoints.Add(new ConsumerEndpointConfig { ... });

// Let configuration auto-load from environment
options.RabbitMq = null; // Uses NeraBaseConfiguration

❌ DON'T

// Don't use direct MassTransit configuration
services.AddMassTransit(x => { ... }); // Use AddNeraMessaging instead

// Don't hardcode connection strings
options.RabbitMq.Host = "production-server"; // Use environment variables

Documentation

• Configuration Reference
• Event Types Guide
• Usage Guide
• Optimization Summary

License

Copyright © Nextera Systems. All rights reserved.