Merge pull request #55 from AntonyVorontsov/feature/full-messages

Made message handlers consume BasicDeliverEventArgs instead of raw string messages.

Author: antonyvorontsov

docs/advanced-usage.md

@@ -11,7 +11,7 @@ Let' say your application is a web API and you want to use both `IConsumingServi
 ```c#
 public class Startup
 {
-    private IConfiguration Configuration { get; }
+    IConfiguration Configuration { get; }
 
     public Startup(IConfiguration configuration)
     {

docs/changelog.md

@@ -2,6 +2,17 @@
 
 All notable changes to this library will be documented in this file.
 
+## [4.3.0] - 2020-10-03
+
+### Added
+
+- `BasicDeliverEventArgs` extensions for parsing messages.
+
+### Changed
+
+- **Breaking!** `IMessageHandler`, `IAsyncMessageHandler`, `INonCyclicMessageHandler` and `IAsyncNonCyclicMessageHandler` get messages in `Handle` methods as `BasicDeliverEventArgs` instead of string values.
+- **Breaking!** `BatchMessageHandler` has been removed, `BaseBatchMessageHandler` is now one and only base class for handling messages in batches. `HandleMessages` method of `BaseBatchMessageHandler` gets a collection of messages as `BasicDeliverEventArgs` instead of bytes.
+
 ## [4.2.0] - 2020-10-01
 
 ### Added

docs/message-consumption.md

@@ -91,7 +91,7 @@ public class Program
 
 public class Worker : BackgroundService
 {
-    private readonly IQueueService _queueService;
+    readonly IQueueService _queueService;
 
     public Worker(IQueueService queueService)
     {
@@ -109,16 +109,16 @@ The second step is to define classes that will take responsibility of handling r
 
 ### Synchronous message handlers
 
-`IMessageHandler` consists of one method `Handle` that gets a message in a string format. You can deserialize that message (if it is a json message) or handle its raw value.
+`IMessageHandler` consists of one method `Handle` that gets a message. You can deserialize that message with `BasicDeliverEventArgs` extensions (described below).
 Thus, a message handler will look like this.
 
 ```c#
 public class CustomMessageHandler : IMessageHandler
 {
-    public void Handle(string message, string routingKey)
+    public void Handle(BasicDeliverEventArgs eventArgs, string matchingRoute)
     {
         // Do whatever you want.
-        var messageObject = JsonConvert.DeserializeObject<YourClass>(message);
+        var messageObject = eventArgs.GetPayload<YourClass>();
     }
 }
 ```
@@ -134,9 +134,9 @@ public class CustomMessageHandler : IMessageHandler
         _logger = logger;
     }
 
-    public void Handle(string message, string routingKey)
+    public void Handle(BasicDeliverEventArgs eventArgs, string matchingRoute)
     {
-        _logger.LogInformation($"I got a message {message} by routing key {routingKey}");
+        _logger.LogInformation($"I got a message {eventArgs.GetMessage()} by routing key {matchingRoute}");
     }
 }
 ```
@@ -153,10 +153,10 @@ public class CustomNonCyclicMessageHandler : INonCyclicMessageHandler
         _logger = logger;
     }
 
-    public void Handle(string message, string routingKey, IQueueService queueService)
+    public void Handle(BasicDeliverEventArgs eventArgs, string matchingRoute, IQueueService queueService)
     {
         _logger.LogInformation("Got a message. I will send it back to another queue.");
-        var response = new { Message = message };
+        var response = new { Message = eventArgs.GetMessage() };
         queueService.Send(response, "exchange.name", "routing.key");
     }
 }
@@ -171,7 +171,7 @@ public class CustomNonCyclicMessageHandler : INonCyclicMessageHandler
 ```c#
 public class CustomAsyncMessageHandler : IAsyncMessageHandler
 {
-    public async Task Handle(string message, string routingKey)
+    public async Task Handle(BasicDeliverEventArgs eventArgs, string matchingRoute)
     {
         // Do whatever you want asynchronously!
     }
@@ -191,10 +191,10 @@ public class CustomAsyncNonCyclicMessageHandler : IAsyncNonCyclicMessageHandler
         _logger = logger;
     }
 
-    public async Task Handle(string message, string routingKey, IQueueService queueService)
+    public async Task Handle(BasicDeliverEventArgs eventArgs, string matchingRoute, IQueueService queueService)
     {
         _logger.LogInformation("You can do something async, e.g. send message back.");
-        var response = new { Message = message };
+        var response = new { Message = eventArgs.GetMessage() };
         await queueService.SendAsync(response, "exchange.name", "routing.key");
     }
 }
@@ -306,21 +306,21 @@ services.AddRabbitMqClient(clientConfiguration)
 The message handling process organized as follows:
 
 - `IQueueMessage` receives a message and delegates it to `IMessageHandlingService`.
-- `IMessageHandlingService` gets a message (as a byte array) and decodes it to the UTF8 string. It also checks if there are any message handlers in a combined collection of `IMessageHandler`, `IAsyncMessageHandler`, `INonCyclicMessageHandler` and `IAsyncNonCyclicMessageHandler` instances and forwards a message to them.
+- `IMessageHandlingService` gets a message and checks if there are any message handlers in a combined collection of `IMessageHandler`, `IAsyncMessageHandler`, `INonCyclicMessageHandler` and `IAsyncNonCyclicMessageHandler` instances and forwards a message to them.
 - All subscribed message handlers (`IMessageHandler`, `IAsyncMessageHandler`, `INonCyclicMessageHandler`, `IAsyncNonCyclicMessageHandler`) process the given message in a given or a default order.
 - `IMessageHandlingService` acknowledges the message by its `DeliveryTag`.
 - If any exception occurs `IMessageHandlingService` acknowledges the message anyway and checks if the message has to be re-send. If exchange option `RequeueFailedMessages` is set `true` then `IMessageHandlingService` adds a header `"re-queue-attempts"` to the message and sends it again with delay in value of `RequeueTimeoutMilliseconds` (default is 200 milliseconds). The number of attempts is configurable and re-delivery will be made that many times as the value of `RequeueAttempts` property. Mechanism of sending delayed messages covered in the message production [documentation](message-production.md).
 - If any exception occurs within handling the message that has been already re-sent that message will not be re-send again (re-send happens only once).
 
 ### Batch message handlers
 
-There are also a feature that you can use in case of necessity of handling messages in batches.
-First of all you have to create a class that inherits a `BatchMessageHandler` class.
+There is a feature that you can use in case of necessity of handling messages in batches.
+First of all you have to create a class that inherits `BaseBatchMessageHandler`.
 You have to set up values for `QueueName` and `PrefetchCount` properties. These values are responsible for the queue that will be read by the message handler, and the size of batches of messages. You can also set a `MessageHandlingPeriod` property value and the method `HandleMessage` will be executed repeatedly so messages in unfilled batches could be processed too, but keep in mind that this property is optional.
 Be aware that batch message handlers **do not declare queues**, so if it does not exist an exception will be thrown. Either declare manually or using RabbitMqClient configuration features.
 
 ```c#
-public class CustomBatchMessageHandler : BatchMessageHandler
+public class CustomBatchMessageHandler : BaseBatchMessageHandler
 {
     readonly ILogger<CustomBatchMessageHandler> _logger;
 
@@ -339,61 +339,51 @@ public class CustomBatchMessageHandler : BatchMessageHandler
 
     public override TimeSpan? MessageHandlingPeriod { get; set; } = TimeSpan.FromMilliseconds(500);
 
-    public override Task HandleMessages(IEnumerable<string> messages, CancellationToken cancellationToken)
+    public override Task HandleMessages(IEnumerable<BasicDeliverEventArgs> messages, CancellationToken cancellationToken)
     {
         _logger.LogInformation("Handling a batch of messages.");
         foreach (var message in messages)
         {
-            _logger.LogInformation(message);
+            _logger.LogInformation(message.GetMessage());
         }
         return Task.CompletedTask;
     }
 }
 ```
 
-If you want to get raw messages as `ReadOnlyMemory<byte>` you can inherit base message handler class.
+After all you have to register that batch message handler via DI.
 
 ```c#
-public class CustomBatchMessageHandler : BaseBatchMessageHandler
-{
-    readonly ILogger<CustomBatchMessageHandler> _logger;
+services.AddBatchMessageHandler<CustomBatchMessageHandler>(Configuration.GetSection("RabbitMq"));
+```
 
-    public CustomBatchMessageHandler(
-        IRabbitMqConnectionFactory rabbitMqConnectionFactory,
-        IEnumerable<BatchConsumerConnectionOptions> batchConsumerConnectionOptions,
-        ILogger<CustomBatchMessageHandler> logger)
-        : base(rabbitMqConnectionFactory, batchConsumerConnectionOptions, logger)
-    {
-        _logger = logger;
-    }
+The message handler will create a separate connection and use it for reading messages.
+When the message collection is full to the size of `PrefetchCount` it will be passed to the `HandleMessage` method.
 
-    public override ushort PrefetchCount { get; set; } = 3;
+### Parsing extensions
 
-    public override string QueueName { get; set; } = "queue.name";
+There are some simple extensions for `BasicDeliverEventArgs` class that helps to parse messages. You have to use `RabbitMQ.Client.Core.DependencyInjection` namespace to enable those extensions.
+There is an example of using those extensions inside a `Handle` method of `IMessageHandler`.
 
-    public override Task HandleMessages(IEnumerable<ReadOnlyMemory<byte>> messages, CancellationToken cancellationToken)
+```c#
+public class CustomMessageHandler : IMessageHandler
+{
+    public void Handle(BasicDeliverEventArgs eventArgs, string matchingRoute)
     {
-        _logger.LogInformation("Handling a batch of messages.");
-        foreach (var message in messages)
-        {
-            var stringifiedMessage = Encoding.UTF8.GetString(message.ToArray());
-            _logger.LogInformation(stringifiedMessage);
-        }
-        return Task.CompletedTask;
+        // You can get string message.
+        var stringifiedMessage = eventArgs.GetMessage();
+
+        // Or object payload.
+        var payload = eventArgs.GetPayload<YourClass>();
+        
+        // Or anonymous object by another example object.
+        var anonymousObject = new { message = string.Empty, number = 0 };
+        var anonymousPayload = eventArgs.GetAnonymousPayload(anonymousObject);
     }
 }
 ```
 
-After all you have to register that batch message handler via DI.
-```c#
-services.AddBatchMessageHandler<CustomBatchMessageHandler>(Configuration.GetSection("RabbitMq"));
-```
-
-The message handler will create a separate connection and use it for reading messages.
-When the message collection is full to the size of `PrefetchCount` they are passed to the `HandleMessage` method.
-Both `BaseBatchMessageHandler` and `BatchMessageHandler` implement `IDisposable` interface, so you can use it for release of resources.
-
-Use this method of getting messages only when you sure that the number of messages that pass through this queue is really huge. Otherwise, messages could stack in the temporary collection of messages waiting to get in full.
+You can also pass `JsonSerializerSettings` to `GetPayload` or `GetAnonymousPayload` methods as well as collection of `JsonConverter` in case you use custom serialization.
 
 For message production features see the [Previous page](message-production.md)
 

docs/message-production.md

@@ -10,7 +10,7 @@ It can be a custom service or a controller.
 [Route("api/[controller]")]
 public class HomeController : Controller
 {
-    private readonly IQueueService _queueService;
+    readonly IQueueService _queueService;
     public HomeController(IQueueService queueService)
     {
         _queueService = queueService;

examples/Examples.AdvancedConfiguration/MessageHandlers/CustomAsyncMessageHandler.cs

@@ -1,11 +1,12 @@
 using System.Threading.Tasks;
 using RabbitMQ.Client.Core.DependencyInjection.MessageHandlers;
+using RabbitMQ.Client.Events;
 
 namespace Examples.AdvancedConfiguration.MessageHandlers
 {
     public class CustomAsyncMessageHandler : IAsyncMessageHandler
     {
-        public async Task Handle(string message, string routingKey)
+        public async Task Handle(BasicDeliverEventArgs eventArgs, string matchingRoute)
         {
             // The message handler does not do anything.
             // It is just an example.

examples/Examples.AdvancedConfiguration/MessageHandlers/CustomAsyncNonCyclicMessageHandler.cs

@@ -1,12 +1,13 @@
 using System.Threading.Tasks;
 using RabbitMQ.Client.Core.DependencyInjection.MessageHandlers;
 using RabbitMQ.Client.Core.DependencyInjection.Services;
+using RabbitMQ.Client.Events;
 
 namespace Examples.AdvancedConfiguration.MessageHandlers
 {
     public class CustomAsyncNonCyclicMessageHandler : IAsyncNonCyclicMessageHandler
     {
-        public async Task Handle(string message, string routingKey, IQueueService queueService)
+        public async Task Handle(BasicDeliverEventArgs eventArgs, string matchingRoute, IQueueService queueService)
         {
             // The message handler does not do anything.
             // It is just an example.

examples/Examples.AdvancedConfiguration/MessageHandlers/CustomMessageHandler.cs

@@ -1,10 +1,11 @@
 using RabbitMQ.Client.Core.DependencyInjection.MessageHandlers;
+using RabbitMQ.Client.Events;
 
 namespace Examples.AdvancedConfiguration.MessageHandlers
 {
     public class CustomMessageHandler : IMessageHandler
     {
-        public void Handle(string message, string routingKey)
+        public void Handle(BasicDeliverEventArgs eventArgs, string matchingRoute)
         {
             // The message handler does not do anything.
             // It is just an example.

examples/Examples.AdvancedConfiguration/MessageHandlers/CustomNonCyclicMessageHandler.cs

@@ -1,11 +1,12 @@
 using RabbitMQ.Client.Core.DependencyInjection.MessageHandlers;
 using RabbitMQ.Client.Core.DependencyInjection.Services;
+using RabbitMQ.Client.Events;
 
 namespace Examples.AdvancedConfiguration.MessageHandlers
 {
     public class CustomNonCyclicMessageHandler : INonCyclicMessageHandler
     {
-        public void Handle(string message, string routingKey, IQueueService queueService)
+        public void Handle(BasicDeliverEventArgs eventArgs, string matchingRoute, IQueueService queueService)
         {
             // The message handler does not do anything.
             // It is just an example.

examples/Examples.AdvancedConfiguration/Startup.cs

@@ -9,7 +9,7 @@ namespace Examples.AdvancedConfiguration
 {
     public class Startup
     {
-        private IConfiguration Configuration { get; }
+        IConfiguration Configuration { get; }
 
         public Startup(IConfiguration configuration)
         {