/RawRabbit

A modern .NET framework for communication over RabbitMq

Primary LanguageC#MIT LicenseMIT

RawRabbit

Build Status Documentation Status NuGet GitHub release

Quick introduction

RawRabbit is a modern .NET client for communication over RabbitMq. It is written for vNext and is uses Microsoft’s new frameworks for logging, configuration and dependecy injection. It targets traditional NET runtimes, DNX runtimes and has all the ground work done for .NET Core. Full documentation available at rawrabbit.readthedocs.org.

Publish/Subscribe

Setting up publish/subscribe in just a few lines of code.

var client = BusClientFactory.CreateDefault();
client.SubscribeAsync<BasicMessage>(async (msg, context) =>
{
  Console.WriteLine($"Recieved: {msg.Prop}.");
});

await client.PublishAsync(new BasicMessage { Prop = "Hello, world!"});

Request/Respond

RawRabbits request/respond (RPC) implementation uses the direct reply-to feature for better performance and lower resource allocation.

var client = BusClientFactory.CreateDefault();
client.RespondAsync<BasicRequest, BasicResponse>(async (request, context) =>
{
  return new BasicResponse();
});

var response = await client.RequestAsync<BasicRequest, BasicResponse>();

Message Context

Message context are passed through to the registered message handler. The context is customizable, meaning that domain specific metadata (like originating country, user claims, global message id etc) can be stored there. In adition to this, RawRabbit comes with an AdvancedMessageContext that is wired up to support more advanced scenarios

Negative Acknowledgement (Nack)

The AdvancedMessageContext has a method Nack() that will perform a basic.reject for the message.

var client = service.GetService<IBusClient<AdvancedMessageContext>>();
client.RespondAsync<BasicRequest, BasicResponse>((req, context) =>
{
    context.Nack(); // the context implements IAdvancedMessageContext.
    return Task.FromResult<BasicResponse>(null);
}, cfg => cfg.WithNoAck(false));

Requeue/Retry

For some scenarios it makes sense to schedule a message for later handling.

subscriber.SubscribeAsync<BasicMessage>(async (msg, context) =>
{
    if (CanNotProcessRightNow(msg))
    {
      context.RetryLater(TimeSpan.FromMinutes(5));
      return;
    }
    // five minutes later, we're here...
});

The AdvancedMessageContext has the properties OriginalSent and NumberOfRetries that can be used to create a "retry x times then nack" strategy.

Extensions

It is easy to write extensions for RawRabbit. The RawRabbit.Extensions NuGet package contains useful extensions, like BulkGet for retrieving multiple messages from multiple queues and Ack/Nack them in bulk:

var bulk = client.GetMessages(cfg => cfg
    .ForMessage<BasicMessage>(msg => msg
        .FromQueues("first_queue", "second_queue")
        .WithBatchSize(4))
    .ForMessage<SimpleMessage>(msg => msg
        .FromQueues("another_queue")
        .GetAll()
        .WithNoAck()
    ));

Customization & Configuration

Dependecy Injection

From the very first commit, RawRabbit was built with pluggability in mind. Registering custom implementations by using the optional argument when calling BusClientFactory.CreateDefault.

var publisher = BusClientFactory.CreateDefault(ioc => ioc
  .AddSingleton<IMessageSerializer, CustomerSerializer>()
  .AddTransient<IChannelFactory, ChannelFactory>()
);

Specified topology settings

All operations have a optional configuration builder that opens up for granular control over the topology

subscriber.SubscribeAsync<BasicMessage>(async (msg, i) =>
{
  //do stuff..
}, cfg => cfg
  .WithRoutingKey("*.topic.queue")
  .WithPrefetchCount(1)
  .WithNoAck()
  .WithQueue(queue =>
    queue
      .WithName("first.topic.queue")
      .WithArgument("x-dead-letter-exchange", "dead_letter_exchange"))
  .WithExchange(exchange =>
    exchange
      .WithType(ExchangeType.Topic)
      .WithAutoDelete()
      .WithName("raw_exchange"))
  );

Project status

Throughput Graph