Vuzol.Abstractions 1.0.1

Vuzol

Vuzol is a lightweight and fluent abstraction over RabbitMQ for .NET. Designed to eliminate boilerplate, it provides automatic topology management, scoped message processing, and robust error handling strategies.

Table of Contents

• Features
• Packages & Installation
• Configuration
• Usage
• Author

<span id="features"></span>

Features

• Fluent Configuration API: Easily set up connections, exchanges, and consumers using a clean, builder-based syntax.

• Automatic Topology Management: Exchanges, Queues, and Bindings are automatically declared on application startup via a background initializer.

• Smart Retry Policy: Integrated support for MaxDeliveryAttempts. Messages are re-queued until the limit is reached, preventing immediate failure on transient errors.

• Dead Letter Support: Built-in routing to a Dead Letter Exchange (vuzol.dead-letter) for messages that exceed their retry limit.

<span id="installation"></span>

Packages & Installation

Vuzol is distributed via two separate NuGet packages to provide maximum flexibility.

1. Vuzol.Abstractions

Contains the core interfaces. This package has zero external dependencies (except for Microsoft abstractions), making it perfect for your core logic.

Includes: IEvent, IConsumer<TEvent>, IEventPublisher.

Usage: Define your events and inject the publisher here.

dotnet add package Vuzol.Abstractions

1. Vuzol.RabbitMQ

The concrete implementation of the Vuzol engine using RabbitMQ as the transport layer.

Includes: AddVuzol registration, VuzolConsumerWorker (background service), and RabbitMQ-specific topology management.

dotnet add package Vuzol.RabbitMQ

<span id="configuration"></span>

Configuration

To integrate Vuzol into your application, you must call the AddVuzol extension method on IServiceCollection. The library utilizes a Fluent API approach, allowing you to configure connection strings, exchange topologies, and consumer behaviors in a single, readable block.

1. Registration Entry Point

The registration process happens during the application startup (usually in Program.cs). You define your broker's behavior using the VuzolOptionsBuilder.

builder.Services.AddVuzol(options => 
{
    // 1. Setup Connection
    options.ConfigureConnection(c => c
        .SetHost("rabbitmq")
        .SetCredentials("guest", "guest"));

    // 2. Register Events (Exchanges)
    options.AddEvent<OrderCreatedEvent>(e => e.SetName("orders.v1"));

    // 3. Register Consumers (Queues & Bindings)
    options.AddConsumer<OrderCreatedConsumer, OrderCreatedEvent>(q => q
        .SetName("order-processor-service")
        .SetMaxDeliveryAttempts(5));
});

2. Configuration Methods

ConfigureConnection(Action<ConnectionOptionsBuilder>)

Defines how Vuzol connects to the RabbitMQ cluster. It maps your settings to the underlying IConnectionFactory.

AddEvent<TEvent>(Action<ExchangeOptionsBuilder<TEvent>>)

• Registers a C# class as a message type.

• Required for IEventPublisher to know where to route messages of type TEvent.

Note: It automatically declares a Fanout Exchange on the broker.

AddConsumer<TConsumer, TEvent>(Action<QueueOptionsBuilder<TConsumer, TEvent>>)

• Connects a message handler to a specific event.

• Creates a Binding between the queue and the event's exchange.

Note: A single event type can have multiple independent consumers. Each consumer will be backed by its own unique queue.

3. Detailed Options Reference

Connection Settings

Event (Exchange) Settings

Consumer (Queue) Settings

<span id="usage"></span>

Usage

This section demonstrates how to implement a standard asynchronous messaging flow using Vuzol.

1. Define an Event

Events are plain objects that carry data. They must implement the IEvent marker interface. Using record is recommended for immutability.

public record OrderPlacedEvent(Guid OrderId, decimal TotalAmount, DateTime CreatedAt) : IEvent;

2. Implement a Consumer

A consumer is a class that handles a specific event. It must implement IConsumer<TEvent>. Vuzol automatically resolves these from the DI container within a scoped lifecycle.

public sealed class OrderPlacedConsumer(ILogger<OrderPlacedConsumer> logger) : IConsumer<OrderPlacedEvent>
{
    public async Task ConsumeAsync(OrderPlacedEvent @event, CancellationToken ct = default)
    {
        logger.LogInformation("Processing order: {OrderId}", @event.OrderId);
        
        await Task.Delay(100, ct); 
    }
}

3. Publish an Event

To send a message, inject the IEventPublisher interface into your service or controller. Vuzol handles the connection and routing to the correct Exchange automatically.

public class CheckoutService(IEventPublisher publisher)
{
    public async Task ExecuteAsync()
    {
        var orderEvent = new OrderPlacedEvent(Guid.NewGuid(), 99.50m, DateTime.UtcNow);

        // Publish to RabbitMQ
        await publisher.PublishAsync(orderEvent);
    }
}

<span id="author"></span>

Author

Developed by Andrii Ivanchyshyn.