Skip to main content

​
Definition

Assembly: CloudNimble.SimpleMessageBus.Core.dll Namespace: CloudNimble.SimpleMessageBus.Core

​
Syntax

CloudNimble.SimpleMessageBus.Core.IMessageHandler

​
Summary

Defines the functionality required for all IMessage processing handlers.

​
Remarks

Message handlers are the core processing units in SimpleMessageBus. They receive messages from queues, process them according to business logic, and handle any errors that occur during processing. Handlers can process multiple message types and are responsible for declaring which types they support.

​
Examples

public class OrderMessageHandler : IMessageHandler
{
    private readonly IOrderService _orderService;

    public OrderMessageHandler(IOrderService orderService)
    {
        _orderService = orderService;
    }

    public IEnumerable<Type> GetHandledMessageTypes()
    {
        yield return typeof(OrderCreatedMessage);
        yield return typeof(OrderUpdatedMessage);
    }

    public async Task OnNextAsync(MessageEnvelope messageEnvelope)
    {
        switch (messageEnvelope.Message)
        {
            case OrderCreatedMessage created:
                await _orderService.ProcessNewOrderAsync(created);
                break;
            case OrderUpdatedMessage updated:
                await _orderService.UpdateOrderAsync(updated);
                break;
        }
    }

    public async Task OnErrorAsync(IMessage message, Exception exception)
    {
        // Log the error and potentially send notifications
        await _orderService.HandleProcessingErrorAsync(message, exception);
    }
}

​
Methods

​
GetHandledMessageTypes Abstract

Specifies which IMessage types are handled by this IMessageHandler.

​
Syntax

System.Collections.Generic.IEnumerable<System.Type> GetHandledMessageTypes()

​
Returns

Type: System.Collections.Generic.IEnumerable<System.Type> An IEnumerable`1 containing all of the IMessage types this IMessageHandler supports. The types must implement IMessage.

​
Examples

public IEnumerable&lt;Type&gt; GetHandledMessageTypes()
{
    yield return typeof(OrderCreatedMessage);
    yield return typeof(OrderCancelledMessage);
    yield return typeof(OrderShippedMessage);
}

​
Remarks

This method is called during handler registration to determine message routing. Return all message types that this handler can process. The framework will ensure that only messages of these types are delivered to this handler’s MessageEnvelope) method.

​
OnErrorAsync Abstract

Specifies what this handler should do when an error occurs during processing.

​
Syntax

System.Threading.Tasks.Task OnErrorAsync(CloudNimble.SimpleMessageBus.Core.IMessage message, System.Exception exception)

​
Parameters

NameTypeDescription
messageCloudNimble.SimpleMessageBus.Core.IMessageThe deserialized IMessage instance that failed.
exceptionSystem.ExceptionThe Exception that occurred during processing.

​
Returns

Type: System.Threading.Tasks.Task A Task reference for the asynchronous function.

​
Examples

public async Task OnErrorAsync(IMessage message, Exception exception)
{
    _logger.LogError(exception, "Failed to process {MessageType} with ID {MessageId}",
        message.GetType().Name, message.Id);

    // Send alert for critical messages
    if (message is CriticalBusinessMessage)
    {
        await _alertService.SendFailureAlertAsync(message, exception);
    }
}

​
Remarks

This method is called when an exception is thrown during message processing. Use this method to implement custom error handling logic such as logging, alerting, or compensating transactions. Note that after this method completes, the message will typically be moved to a poison queue unless retry policies dictate otherwise.

​
OnNextAsync Abstract

Specifies what this handler should do when it is time to process the MessageEnvelope.

​
Syntax

System.Threading.Tasks.Task OnNextAsync(CloudNimble.SimpleMessageBus.Core.MessageEnvelope messageEnvelope)

​
Parameters

NameTypeDescription
messageEnvelopeCloudNimble.SimpleMessageBus.Core.MessageEnvelopeThe MessageEnvelope to process.

​
Returns

Type: System.Threading.Tasks.Task A Task reference for the asynchronous function.

​
Examples

public async Task OnNextAsync(MessageEnvelope messageEnvelope)
{
    // Extract metadata if available
    var userId = messageEnvelope.Metadata?.GetValueOrDefault("UserId");

    // Process based on message type
    switch (messageEnvelope.Message)
    {
        case OrderCreatedMessage order:
            await ProcessOrderAsync(order, userId?.ToString());
            break;
        default:
            throw new NotSupportedException($"Message type {messageEnvelope.Message.GetType()} not supported");
    }
}

​
Remarks

This is the main processing method for messages. The framework calls this method when a message of a supported type (as declared by IMessageHandler.GetHandledMessageTypes) is received from the queue. The message is pre-deserialized and available in the MessageEnvelope.Message property. Any unhandled exceptions thrown from this method will trigger a call to Exception).