Ludamo.ServiceBus.Extension 1.0.0-alpha.4

Table of contents

• Ludamo.ServiceBus.Extension
  • Description
  • Features
  • Installation
  • Quick Start
  • Publishing Messages
  • Subscribing to Messages

Ludamo.ServiceBus.Extension

A lightweight abstraction library over Azure Service Bus that simplifies message publishing and subscription handling in .NET applications.

Description

Ludamo.ServiceBus.Extension provides a clean and easy-to-use API for working with Azure Service Bus. It offers streamlined configuration for both publishers and subscribers, automatic message serialization/deserialization, and seamless integration with ASP.NET Core dependency injection.

Features

• Simple configuration through extension methods (AddBus, WithPublishers, WithSubscriber)
• Automatic registration and resolution of message handlers
• Type-safe message publishing through the IBusPublisher interface
• Support for customizing message properties before publishing through PublishContext
• Asynchronous message processing
• Integration with ASP.NET Core dependency injection system
• Support for both queue and topic/subscription scenarios

Installation

dotnet add package Ludamo.ServiceBus.Extension

Quick Start

Publishing Messages

The Ludamo.ServiceBus.Extension library provides a clean and simple API for publishing messages to Azure Service Bus queues or topics.

1. Define your message

All messages must implement the IMessage marker interface:

using Ludamo.ServiceBus.Extension.Interfaces;
public record OrderCreated : IMessage 
{
    public Guid Id { get; init; } 
    
    public required string Address { get; init; } 
    
    public required string Customer { get; init; } 
    
    public required string AccountNumber { get; init; }
}

2. Configure the publisher

In your Program.cs or Startup.cs, configure the publisher within the service collection:

builder.Services.AddBus<Program>()
    .WithPublishers(configuration =>
    {
        configuration.Register<OrderCreated>("topic-name", "connection-string");
    });

Note: If you register the same type of message more than once, the last registration will take precedence.

You can also authenticate using Azure.Identity.

builder.Services.AddBus<Program>()
    .WithPublishers(configuration =>
    {
        configuration.Register<OrderCreated>("topic-name", new DefaultAzureCredential());
    });

The Azure Identity library provides easy Azure Active Directory support for authentication.

Customizing message serialization

For cases where you need to customize the message serialization process before publishing, you can use the ConfigureSerialization method during type registration.

builder.Services.AddBus<Program>()
    .WithPublishers(configuration =>
    {
        configuration
            .Register<OrderCreated>("topic-name", "connection-string")
            .ConfigureSerialization(new JsonSerializerOptions(JsonSerializerDefaults.Web));
    });

3. Publish a message

To publish a message, inject the IBusPublisher interface into your class and call the PublishAsync method:

public class OrderService {
    private readonly IBusPublisher _publisher;
    
    public OrderService(IBusPublisher publisher)
    {
        _publisher = publisher;
    }

    public async Task CreateOrder(string customer, string address, string accountNumber)
    {
        // Your business logic
        var orderId = Guid.NewGuid();
        
        // Publish message to Service Bus
        await _publisher.PublishAsync(new OrderCreated
        {
            Id = orderId,
            Address = address,
            Customer = customer,
            AccountNumber = accountNumber
        });
    }
}

Customize message properties

You can customize the message properties like Label, SessionId, ReplyTo, etc. before publishing by using the PublishContext action callback.

await bus.PublishAsync(new OrderCreated
    {
        Id = Guid.NewGuid(),
        Address = $"Street {rnd.Next(1, 10)}",
        Customer = "Jhon Doe",
        AccountNumber = "12345"
    }, context =>
    {
        context.SetLabel("label");
        
        context.SetReplyToSessionId("sessionId");
        
        context.SetSessionId("sessionId");
    });

Subscribing to Messages

The Ludamo.ServiceBus.Extension library provides a clean and simple API for subscribing to and handling messages from Azure Service Bus queues or topics.

1. Create a Message Handler

To process a message, create a class that implements the IMessageHandler<T> interface where is the message type you want to handle: T

using Ludamo.ServiceBus.Extension.Interfaces;

namespace YourNamespace.MessageHandlers;

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

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

    public Task Handle(OrderCreated message, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation("Order created, info\n{OrderData}", message);
        
        // Your business logic for processing the message here
        
        return Task.CompletedTask;
    }
}

2. Configure the Subscriber

In your Prgoram.cs or Startup.cs, configure the subscriber within the service collection: Program.cs

builder.Services.AddBus<Program>()
    .WithSubscribers(configuration =>
    {
        configuration.Register<OrderCreated>(
            topicName: "topic-name", 
            subscriptionName: "subscription-name", 
            connectionString: "connection-string");
    });

Note: When registering a subscriber, you need to specify:

• topicName: The name of the topic to subscribe to
• subscriptionName: The name of the subscription in that topic
• connectionString: The connection string to Azure Service Bus

You can also authenticate using Azure.Identity just like with publishers:

builder.Services.AddBus<Program>()
    .WithSubscribers(configuration =>
    {
        configuration.Register<OrderCreated>(
            topicName: "topic-name", 
            subscriptionName: "subscription-name", 
            new DefaultAzureCredential());

Customizing Message Deserialization

To customize the deserialization process for received messages, you can use the ConfigureSerialization method during type registration.

builder.Services.AddBus<Program>()
    .WithSubscribers(configuration =>
    {
        configuration
            .Register<OrderCreated>(
                topicName: "topic-name", 
                subscriptionName: "subscription-name", 
                connectionString: "connection-string")
            .ConfigureSerialization(new JsonSerializerOptions(JsonSerializerDefaults.Web));
    });

3. Automatic Handler Registration

An important feature of Ludamo.ServiceBus.Extension is that it automatically registers all message handlers that implement IMessageHandler<T> in the same assembly as the marker type used in AddBus<TMarker>().

This means you don't have to manually register your handlers in the DI container, just make sure they implement the correct interface and are in the same assembly as your marker type.

ToDos

• Add the ability to subscribe to messages with labels
• Send batches of messages
• Schedule messages during publishing
• When subscribing to a message, defer it to process the message later
• Reject messages
• (Maybe) Add retry logic when subscribing or publishing