RetailSolutions.Shared.Events 1.3.1381

RetailSolutions.Shared.Events

Biblioteca .NET para comunicação assíncrona via RabbitMQ, com abstrações de alto nível para publicação e consumo de mensagens em arquiteturas de microsserviços.

Sumário

• Recursos
• Requisitos
• Instalação
• Início Rápido
  • Consumer
  • Publisher
• Configuração via appsettings.json
• Referência de API
  • ConsumerOptions
  • PublisherOptions
• Exemplos Avançados
• Estrutura do Projeto

Recursos

Requisitos

• .NET 10.0 ou superior
• RabbitMQ Server 3.8 ou superior
• Microsoft.AspNetCore.App

Instalação

dotnet add package RetailSolutions.Shared.Events

Início Rápido

Consumer

1. Registrar o consumer no Program.cs:

using RetailSolutions.Shared.Events;

var builder = WebApplication.CreateBuilder(args);

builder.AddConsumer<OrderCreatedHandler>(new ConsumerOptions
{
    ConnectionString = "amqp://guest:guest@localhost:5672",
    ApplicationName  = "OrderService",
    QueueName        = "orders",
    ExchangeName     = "orders-exchange",
    RoutingKey       = "#",
    ConfigureDlq     = true
});

var app = builder.Build();

app.UseConsumer(); // valida a conexão no startup
app.Run();

2. Implementar o handler:

public class OrderCreatedHandler : IRabbitMQMessageHandler
{
    private readonly ILogger<OrderCreatedHandler> _logger;

    public OrderCreatedHandler(ILogger<OrderCreatedHandler> logger)
        => _logger = logger;

    public async Task<bool> HandleAsync(RabbitMQMessageEventArgs args)
    {
        _logger.LogInformation("Message received. RoutingKey: {Key}", args.RoutingKey);

        // var order = JsonSerializer.Deserialize<OrderCreatedEvent>(args.Body);

        // Retorna true  → ACK  (mensagem processada com sucesso)
        // Retorna false → NACK (mensagem rejeitada / reenfileirada)
        return true;
    }
}

Publisher

1. Registrar o publisher:

builder.AddPublisher(new PublisherOptions
{
    ConnectionString = "amqp://guest:guest@localhost:5672",
    ApplicationName  = "OrderService",
    ExchangeName     = "orders-exchange",
    Persistent       = true
});

var app = builder.Build();

app.UsePublisher(); // valida a conexão no startup
app.Run();

2. Publicar mensagens via injeção de dependência:

public class OrderService(IRabbitMQPublisher publisher)
{
    public async Task CreateOrderAsync(Order order)
    {
        // Publicar string simples
        await publisher.PublishAsync("order.created", "Order created");

        // Publicar objeto (serializado automaticamente para JSON)
        await publisher.PublishAsync("order.created", new OrderCreatedEvent
        {
            OrderId      = order.Id,
            CustomerName = order.CustomerName,
            TotalAmount  = order.Total
        });

        // Publicar com headers customizados
        await publisher.PublishAsync("order.created", order, new Dictionary<string, object>
        {
            ["source"]  = "OrderService",
            ["version"] = "1.0"
        });
    }
}

Configuração via appsettings.json

{
  "RabbitMQ": {
    "Consumer": {
      "ConnectionString": "amqp://guest:guest@localhost:5672",
      "ApplicationName": "OrderService",
      "QueueName": "orders",
      "ExchangeName": "orders-exchange",
      "RoutingKey": "#",
      "RetryPolicy": 5,
      "EnableAutoReconnect": true,
      "ConfigureDlq": true
    },
    "Publisher": {
      "ConnectionString": "amqp://guest:guest@localhost:5672",
      "ApplicationName": "OrderService",
      "ExchangeName": "orders-exchange",
      "Persistent": true
    }
  }
}

builder.AddConsumer<MyHandler>();          // lê "RabbitMQ:Consumer"
builder.AddPublisher();                    // lê "RabbitMQ:Publisher"

// Seção customizada
builder.AddConsumer<MyHandler>("Messaging:RabbitMQ:Consumer");

Referência de API

ConsumerOptions

PublisherOptions

Exemplos Avançados

Consumer em Console App (IHost)

var builder = Host.CreateApplicationBuilder(args);

builder.AddConsumer<MyHandler>(new ConsumerOptions
{
    ConnectionString = "amqp://guest:guest@localhost:5672",
    ApplicationName  = "ConsoleApp",
    QueueName        = "console-queue",
    ExchangeName     = "console-exchange"
});

var host = builder.Build();
await host.RunAsync();

Publisher em Console App

var builder = Host.CreateApplicationBuilder(args);

builder.AddPublisher(new PublisherOptions
{
    ConnectionString = "amqp://guest:guest@localhost:5672",
    ApplicationName  = "ConsoleApp",
    ExchangeName     = "console-exchange"
});

var host = builder.Build();
var publisher = host.Services.GetRequiredService<IRabbitMQPublisher>();

await publisher.PublishAsync("test.message", "Hello from console app!");
await host.RunAsync();

Validação de conexão no startup

// Lança exceção se não conectar dentro do timeout
app.UseConsumer(timeout: TimeSpan.FromSeconds(60), throwOnFailure: true);

// Apenas loga warning se não conectar (não bloqueia a inicialização)
app.UsePublisher(timeout: TimeSpan.FromSeconds(60), throwOnFailure: false);

Dead Letter Queue

builder.AddConsumer<MyHandler>(new ConsumerOptions
{
    // ...
    ConfigureDlq     = true,
    DlqExchangeName  = "orders-exchange.dlx",  // opcional, auto-gerado se omitido
    DlqQueueName     = "orders.dlq",           // opcional, auto-gerado se omitido
    DlqRoutingKey    = "#"
});

Estrutura do Projeto

RetailSolutions.Shared.Events/
├── IEventBus.cs
├── IntegrationEvent.cs
└── RabbitMQ/
    ├── Interfaces & Models
    │   ├── IRabbitMQConsumer.cs
    │   ├── IRabbitMQMessageHandler.cs
    │   ├── IRabbitMQPublisher.cs
    │   ├── RabbitMQMessageEventArgs.cs
    │   ├── ConsumerOptions.cs
    │   └── PublisherOptions.cs
    ├── Base
    │   └── RabbitMQConnectionBase.cs
    ├── Implementations
    │   ├── RabbitMQConsumer.cs
    │   ├── RabbitMQConsumerService.cs
    │   └── RabbitMQPublisher.cs
    └── Extensions
        ├── RabbitMQConsumerExtensions.cs
        └── RabbitMQPublisherExtensions.cs

Links

• Retail Solutions
• Documentação do RabbitMQ
• Documentação do .NET