Started making advanced usage docs.

Author: antonyvorontsov

advanced-usage.md

@@ -0,0 +1,6 @@
+# Advanced usage
+
+todo
+
+
+For basic message consumption features see the [Previous page](message-consumption.md)

docs/message-consumption.md

@@ -311,4 +311,6 @@ The message handling process is organized as follows:
 - 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 `"requeued"` to the message and sends it again with delay in 60 seconds. 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).
 
-For message production features see the [Previous page](message-production.md)
+For message production features see the [Previous page](message-production.md)
+
+For more information about advanced usage of the RabbitMQ client see the [Next page](advanced-usage.md)

docs/readme.md

@@ -4,10 +4,12 @@ These files cover all functionality of the library and if the new feature comes
 Documentation consists of four sections. **RabbitMQ configuration section** covers ways of configuring the connection to the RabbitMQ host or multiple hosts (HA cluster).
 **Exchange configuration section** explains the difference between consumption and production exchanges in terms of this library as well as specific nuances of configuring them.
 **Message production section** says about features of sending messages and **message consuming section** covers ways of receiving and handling messages.
+Last section **Advanced usage** covers specific usage of the RabbitMQ client that can be useful for users who want to control behavior of RabbitMQ client tighter.
 
 ## Table of contents
 
 - [RabbitMQ configuration](rabbit-configuration.md)
 - [Exchange configuration](exchange-configuration.md)
 - [Message production](message-production.md)
-- [Message consumption](message-consumption.md)
+- [Message consumption](message-consumption.md)
+- [Advanced usage](advanced-usage.md)

readme.md

@@ -20,13 +20,13 @@ public void ConfigureServices(IServiceCollection services)
 {
     var rabbitMqSection = Configuration.GetSection("RabbitMq");
     var exchangeSection = Configuration.GetSection("RabbitMqExchange");
-    
+
     services.AddRabbitMqClient(rabbitMqSection)
         .AddProductionExchange("exchange.name", exchangeSection);
 }
 ```
 
-By calling `AddRabbitMqClient` you add `IQueueService` that provides functionality of sending messages to queues. `AddProductionExchange` configures exchange to queues bindings (presented in json configuration) that allow messages to route properly. 
+By calling `AddRabbitMqClient` you add `IQueueService` that provides functionality of sending messages to queues. `AddProductionExchange` configures exchange to queues bindings (presented in json configuration) that allow messages to route properly.
 Example of `appsettings.json` is two sections below. You can also configure everything manually. For more information, see [rabbit-configuration](./docs/rabbit-configuration.md) and [exchange-configuration](./docs/exchange-configuration.md) documentation files.
 
 Now you can inject an instance of `IQueueService` inside anything you want.
@@ -69,7 +69,7 @@ _queueService.Send(
 ```
 
  The mechanism of sending delayed messages described in the [documentation](./docs/message-production.md). Dive into it for more detailed information.
- 
+
 ### Consumer
 
 After making the message production possible let's make the consumption possible too! Imagine that a consumer is a simple console application.
@@ -79,27 +79,27 @@ class Program
 {
     const string ExchangeName = "exchange.name";
     public static IConfiguration Configuration { get; set; }
-    
+
     static void Main()
     {
         var builder = new ConfigurationBuilder()
             .SetBasePath(Directory.GetCurrentDirectory())
             .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);
         Configuration = builder.Build();
-    
+
         var serviceCollection = new ServiceCollection();
         ConfigureServices(serviceCollection);
-    
+
         var serviceProvider = serviceCollection.BuildServiceProvider();
         var queueService = serviceProvider.GetRequiredService<IQueueService>();
         queueService.StartConsuming();
     }
-    
+
     static void ConfigureServices(IServiceCollection services)
     {
         var rabbitMqSection = Configuration.GetSection("RabbitMq");
         var exchangeSection = Configuration.GetSection("RabbitMqExchange");
-    
+
         services.AddRabbitMqClient(rabbitMqSection)
             .AddConsumptionExchange("exchange.name", exchangeSection)
             .AddMessageHandlerSingleton<CustomMessageHandler>("routing.key");
@@ -132,20 +132,82 @@ public class CustomMessageHandler : IMessageHandler
     {
         _logger = logger;
     }
-    
+
     public void Handle(string message, string routingKey)
     {
         // Do whatever you want with the message.
         _logger.LogInformation("Hello world");
     }
 }
 ```
-There are async and non-cyclic message handler types, which allow you to do additional stuff. For more information, see the [message-consuming](./docs/message-consumption.md) documentation file.
+
+If you want to use an async magic then implement your custom `IAsyncMessageHandler`.
+
+```c#
+public class CustomAsyncMessageHandler : IAsyncMessageHandler
+{
+    readonly ILogger<CustomAsyncMessageHandler> _logger;
+    public CustomAsyncMessageHandler(ILogger<CustomAsyncMessageHandler> logger)
+    {
+        _logger = logger;
+    }
+
+    public async Task Handle(string message, string routingKey)
+    {
+	   // await something.
+    }
+}
+```
+
+If you want to send messages from the `Handle` method inside your message handler then use `INonCyclicMessageHandler`.
+You can't inject  `IQueueService` inside any message handlers, otherwise you will get a cyclic dependency exception. But `INonCyclicMessageHandler` allows you to avoid this as it accepts an instance of `IQueueService` as a parameter of the method `Handle`.
+
+```c#
+public class MyNonCyclicMessageHandler : INonCyclicMessageHandler
+{
+    // Inject anything you want except IQueueService.
+    readonly ILogger<MyNonCyclicMessageHandler> _logger;
+    public MyNonCyclicMessageHandler(ILogger<MyNonCyclicMessageHandler> logger)
+    {
+        _logger = logger;
+    }
+
+    public void Handle(string message, string routingKey, IQueueService queueService)
+    {
+        // Send anything you want using IQueueService instance.
+        var anotherMessage = new MyMessage { Foo = "Bar" };
+        queueService.Send(anotherMessage, "exchange.name", "routing.key");
+    }
+}
+```
+
+`INonCyclicMessageHandler` has its asynchrony analogue IAsyncNonCyclicMessageHandler`.
+
+```c#
+public class MyAsyncNonCyclicMessageHandler : IAsyncNonCyclicMessageHandler
+{
+    // Inject anything you want except IQueueService.
+    readonly ILogger<MyAsyncNonCyclicMessageHandler> _logger;
+    public MyNonCyclicMessageHandler(ILogger<MyAsyncNonCyclicMessageHandler> logger)
+    {
+        _logger = logger;
+    }
+
+    public async Task Handle(string message, string routingKey, IQueueService queueService)
+    {
+        // Do async stuff.
+        var anotherMessage = new MyMessage { Foo = "Bar" };
+        await queueService.SendAsync(anotherMessage, "exchange.name", "routing.key");
+    }
+}
+```
+
+You can register any of those message handlers the same way you registered `IMessageHandler` before. There are similar extension methods for each type of message handlers. For more information, see the [message-consuming](./docs/message-consumption.md) documentation file.
 
 You can also find example projects in the repository inside the [examples](./examples) directory.
 
 ### Configuration
- 
+
 In both cases for producing and consuming messages the configuration file is the same. `appsettings.json` consists of those sections: (1) settings to connect to the RabbitMQ server and (2) sections that configure exchanges and queue bindings. You can have multiple exchanges and one configuration section per each exchange.
 Exchange sections define how to bind queues and exchanges with each other using specified routing keys (or patterns). You allowed to bind a queue to an exchange with more than one routing key, but if there are no routing keys in the queue section, then that queue will be bound to the exchange with its name.
 
@@ -175,6 +237,10 @@ Exchange sections define how to bind queues and exchanges with each other using
 
 For more information about `appsettings.json` and manual configuration features, see [rabbit-configuration](./docs/rabbit-configuration.md) and [exchange-configuration](./docs/exchange-configuration.md) documentation files.
 
+## Important nuances and advanced usage
+
+RabbitMQ client implemented in this library (class which implements `IQueueService`) opens two connections to the RabbitMQ server. One connection is used for message production and the other one is for message consumption. This behavior embedded since 3.2.0 version of the library.
+
 ## Changelog
 
 All notable changes are being tracked in the [changelog](./docs/changelog.md) file.