Nera.Lib.Messaging.Abstractions 1.0.1

Nera.Lib.Messaging.Abstractions

Messaging abstractions for Nextera applications, providing standardized interfaces and implementations for both inter-service and in-service event communication.

Table of Contents

• Overview
• Integration Events
• In-Service Events
• Best Practices
• Examples
• Troubleshooting

Overview

Nera.Lib.Messaging.Abstractions provides a consistent messaging framework for the Nextera microservice architecture. The library:

• Leverages MassTransit and RabbitMQ as message broker for cross-service communication
• Provides in-memory event bus for in-service event handling
• Standardizes event communication patterns across the system
• Simplifies message handling with base classes and automatic registration

Key Components

1. Cross-Service Communication:

   • IIntegrationEvent - Interface for events shared across services
   • IntegrationMessageBase - Base class for integration events
   • IEventBus - Interface for publishing integration events
   • ConsumerBase<T> - Base class for consuming integration events

2. In-Service Communication:

   • IInServiceEvent - Interface for events handled within the same service
   • InServiceEventBase - Base class for in-service events
   • IInServiceEventBus - Interface for publishing and handling in-service events
   • InServiceEventHandlerBase<T> - Base class for handling in-service events

Integration Events

Integration events are used for communication between different services.

Creating an Integration Event

using Nera.Lib.Messaging.Abstractions;

namespace YourService.Events;

public record OrderCompletedIntegrationEvent(
    Guid OrderId,
    string CustomerEmail,
    decimal TotalAmount) : IntegrationMessageBase;

Publishing an Integration Event

public class OrderService
{
    private readonly IEventBus _eventBus;
    private readonly IMessageContextAccessor _contextAccessor;
    
    public OrderService(IEventBus eventBus, IMessageContextAccessor contextAccessor)
    {
        _eventBus = eventBus;
        _contextAccessor = contextAccessor;
    }
    
    public async Task CompleteOrderAsync(Order order)
    {
        // Business logic...
        
        // Create and publish event
        var @event = new OrderCompletedIntegrationEvent(
            order.Id,
            order.CustomerEmail,
            order.TotalAmount);
            
        await _eventBus.Publish(@event);
    }
}

Consuming an Integration Event

using MassTransit;
using Microsoft.Extensions.Logging;
using Nera.Lib.Messaging.Abstractions;

namespace YourService.Consumers;

public class OrderCompletedIntegrationEventConsumer 
    : ConsumerBase<OrderCompletedIntegrationEvent>
{
    private readonly IEmailService _emailService;
    
    public OrderCompletedIntegrationEventConsumer(
        ILogger<OrderCompletedIntegrationEventConsumer> logger,
        IEmailService emailService)
        : base(logger)
    {
        _emailService = emailService;
    }
    
    public override async Task Consume(
        ConsumeContext<OrderCompletedIntegrationEvent> context)
    {
        LogMessageReceived(context);
        
        try
        {
            await _emailService.SendOrderConfirmationAsync(
                context.Message.CustomerEmail,
                context.Message.OrderId,
                context.Message.TotalAmount);
                
            LogMessageProcessed(context);
        }
        catch (Exception ex)
        {
            LogMessageError(context, ex);
            throw;
        }
    }
}

In-Service Events

In-service events are used for communication between components within the same service.

Creating an In-Service Event

using Nera.Lib.Messaging.Abstractions;

namespace YourService.Events;

public record UserProfileUpdatedEvent(
    Guid UserId,
    string Username,
    string NewEmail) : InServiceEventBase;

Creating an In-Service Event Handler

using Microsoft.Extensions.Logging;
using Nera.Lib.Messaging.Abstractions;

namespace YourService.Handlers;

public class UserProfileUpdatedEventHandler 
    : InServiceEventHandlerBase<UserProfileUpdatedEvent>
{
    private readonly INotificationService _notificationService;
    
    public UserProfileUpdatedEventHandler(
        ILogger<UserProfileUpdatedEventHandler> logger,
        INotificationService notificationService)
        : base(logger)
    {
        _notificationService = notificationService;
    }
    
    protected override async Task HandleInternal(
        UserProfileUpdatedEvent @event, 
        CancellationToken cancellationToken)
    {
        await _notificationService.NotifyEmailChangeAsync(
            @event.UserId,
            @event.Username,
            @event.NewEmail);
    }
}

Publishing an In-Service Event

public class UserService
{
    private readonly IInServiceEventBus _eventBus;
    
    public UserService(IInServiceEventBus eventBus)
    {
        _eventBus = eventBus;
    }
    
    public async Task UpdateUserProfileAsync(UpdateProfileRequest request)
    {
        // Business logic...
        
        // Create and publish in-service event
        var @event = new UserProfileUpdatedEvent(
            request.UserId,
            request.Username,
            request.NewEmail);
            
        await _eventBus.PublishEvent(@event);
    }
}

Registration

Register Messaging Services

public void ConfigureServices(IServiceCollection services)
{
    // Register all messaging services
    services.AddMessagingServices();
    
    // Configure service name
    services.Configure<MessagingOptions>(options =>
    {
        options.ServiceName = "your-service-name";
    });
}

Advanced Registration Options

// Register without automatic handler discovery
services.AddMessagingServices(registerInternalHandlers: false);

// Register in-service event handlers from specific assembly
services.AddInServiceEventHandlers(typeof(YourClass).Assembly);

Best Practices

1. Naming Conventions

   • Integration Events: {Entity}{Action}IntegrationEvent
   • In-Service Events: {Entity}{Action}Event
   • Consumers: {EventName}Consumer
   • Handlers: {EventName}Handler

2. Event Design

   • Design events to be immutable
   • Use C# records for events
   • Include only necessary data
   • Consider including context information

3. Error Handling

   • Always use proper error handling in consumers and handlers
   • Configure retry policies for transient errors
   • Consider the consequences of event failure

4. When to Use In-Service Events

   • Decoupling components within a service
   • Asynchronous post-processing operations
   • Reducing tight coupling between modules
   • Performance optimization by moving secondary processing out of the main flow

Troubleshooting

Common issues and their solutions:

1. "No consumers available for message"

   • Check event namespace and naming
   • Ensure AddMessagingServices() is called
   • Verify consumer class inheritance

2. "Connection to RabbitMQ failed"

   • Check environment variables: ENV_RABBIT_MQ_CONNECTION, ENV_RABBIT_MQ_USERNAME, ENV_RABBIT_MQ_PASSWORD
   • Verify RabbitMQ server is running

3. "No handlers registered for event"

   • Verify handler registration
   • Check namespace and type matching
   • Ensure handler classes inherit from correct base class