EasyCore.RabbitMQ 8.3.0

🐇 EasyCore.RabbitMQ

EasyCore.RabbitMQ is a RabbitMQ infrastructure client for .NET 8. Built on RabbitMQ.Client, it provides DI registration, connect, publish, subscribe, and Ack/Nack. It is not tied to IEvent / EventBus — use it standalone, or via the EasyCore.EventBus.RabbitMQ adapter.

🌍 Language

• Chinese: README.md
• English (this document)

📚 Table of Contents

• 1. Positioning
• 2. Relation to EventBus
• 3. Requirements
• 4. Installation
• 5. Quick Start
• 6. API Overview
• 7. Options (RabbitMQOptions)
• 8. FAQ
• 9. License

1. 🎯 Positioning

1.1 Design Principles

2. Relation to EventBus

┌─────────────────────────────┐
│  App code (any payload)     │
└──────────────┬──────────────┘
               │ IRabbitMQClient
               ▼
┌─────────────────────────────┐
│  EasyCore.RabbitMQ (this)   │  ← infrastructure client
└──────────────┬──────────────┘
               │ RabbitMQ.Client
               ▼
          RabbitMQ Broker

┌─────────────────────────────┐
│ EasyCore.EventBus.RabbitMQ  │  ← adapter: IEvent / Handler
│   └── uses this client      │
└─────────────────────────────┘

3. ⚙ Requirements

4. 📥 Installation

dotnet add package EasyCore.RabbitMQ

5. ⚡ Quick Start

5️⃣.1️⃣ Register DI

using EasyCore.RabbitMQ;

builder.Services.AddEasyCoreRabbitMQ(o =>
{
    o.HostName = "localhost";
    o.UserName = "guest";
    o.Password = "guest";
    o.Port = 5672;
    o.ExchangeName = "EasyCore.EventBus";
    o.ExchangeType = "topic";
    o.VirtualHost = "/";
});

5️⃣.2️⃣ Publish

public sealed class OrderPublisher
{
    private readonly IRabbitMQClient _client;

    public OrderPublisher(IRabbitMQClient client) => _client = client;

    public async Task PublishAsync(string orderId, CancellationToken ct = default)
    {
        await _client.ConnectAsync(ct);

        var body = Encoding.UTF8.GetBytes($$"""{"orderId":"{{orderId}}"}""");
        var headers = new Dictionary<string, object>
        {
            ["x-message-type"] = "OrderCreated"
        };

        await _client.PublishAsync(
            routingKey: "order.created",
            body: body,
            headers: headers,
            cancellationToken: ct);
    }
}

5️⃣.3️⃣ Subscribe with Ack / Nack

public sealed class OrderConsumer : BackgroundService
{
    private readonly IRabbitMQClient _client;

    public OrderConsumer(IRabbitMQClient client) => _client = client;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await _client.ConnectAsync(stoppingToken);

        await _client.SubscribeAsync(
            routingKeys: new[] { "order.created", "order.updated" },
            handler: async (msg, ct) =>
            {
                try
                {
                    var json = Encoding.UTF8.GetString(msg.Body.Span);
                    // handle business…
                    _client.Ack(msg.DeliveryTag);
                }
                catch
                {
                    _client.Nack(msg.DeliveryTag, requeue: true);
                }

                await Task.CompletedTask;
            },
            cancellationToken: stoppingToken);
    }
}

RabbitMQDeliveredMessage fields: RoutingKey, Body, Headers, DeliveryTag, CorrelationId.

6. 🧩 API Overview

IRabbitMQClient implements IAsyncDisposable — dispose on shutdown.

7. Options (RabbitMQOptions)

8. ❓ FAQ

Q: This package vs EasyCore.EventBus.RabbitMQ?
A: Use the EventBus adapter for IEvent, handlers, and retries. Use this package for raw byte publish/subscribe.

Q: Must I call ConnectAsync first?
A: Yes — connect before publish or subscribe so the connection and exchange are ready.

Q: How is the subscription queue named?
A: From AppName (or entry assembly) plus QueueName, then bound to the given routing keys.

Q: When to requeue on Nack?
A: Transient failures: requeue: true. Poison messages: false (or dead-letter) to avoid loops.

Q: Multiple hosts?
A: Pass comma-separated hosts in HostName; failover follows RabbitMQ.Client behavior.

9. 📄 License

MIT — see the repository LICENSE, or the NuGet package metadata.

🤝 Contributing

Issues and PRs are welcome. After changing this package, verify EasyCore.EventBus.RabbitMQ and related demos.