Covered wildcard extensions in the documentation.

Author: Anton Vorontsov

docs/message-consumption.md

@@ -2,10 +2,10 @@
 
 ### Starting a consumer
 
-The first step that needs to be done to retrieve messages from queues is to start a consumer. This can be achieved by calling `StartConsuming` method of `IQueueService`.
-Without calling `StartConsuming` consumption exchanges will work only in production mode.
+The first step that has to be done to retrieve messages from queues is to start a consumer. This can be achieved by calling `StartConsuming` method of the `IQueueService`.
+Consumption exchanges will work only in message-production mode if `StartConsuming` method won't be called.
 
-Let's say that your configuration look like this.
+Let's say that your configuration looks like this.
 
 ```c#
 public class Startup
@@ -27,13 +27,13 @@ public class Startup
 }
 ```
 
-You can register an `IHostedService` and inject the instance of `IQueueService` into it.
+You can register an `IHostedService` and inject the instance of the `IQueueService` into it.
 
 ```c#
 services.AddSingleton<IHostedService, ConsumingService>();
 ```
 
-And then simply call `StartConsuming` so consumer can work in a background.
+And then simply call `StartConsuming` so a consumer can work in the background.
 
 ```c#
 public class ConsumingService : IHostedService
@@ -64,7 +64,7 @@ public class ConsumingService : IHostedService
 }
 ```
 
-Otherwise you can implement a worker service template from .Net Core 3 like this.
+Otherwise, you can implement a worker service template from .Net Core 3 like this.
 
 ```c#
 public class Program
@@ -132,30 +132,40 @@ public class Startup
 }
 ```
 
-The RabbitMQ client configuration and exchange configuration sections not specified in this example, but covered [here](rabbit-configuration.md) and [here](exchange-configuration.md).
+RabbitMQ client and exchange configuration sections are not specified in this example, but covered [here](rabbit-configuration.md) and [here](exchange-configuration.md).
 
-`IMessageHandler` implementation will "listen" for messages by specified routing key, or a collection of routing keys.
+`IMessageHandler` implementation will "listen" for messages by specified routing key, or a collection of routing keys. If it is necessary you can also register multiple message handler at once.
 ```c#
 services.AddRabbitMqClient(clientConfiguration)
     .AddExchange("ExchangeName", isConsuming: true, exchangeConfiguration)
-    .AddMessageHandlerSingleton<CustomMessageHandler>(new[] { "first.routing.key", "second.routing.key", "third.routing.key" });
+    .AddMessageHandlerSingleton<CustomMessageHandler>("first.routing.key");
+    .AddMessageHandlerSingleton<AnotherCustomMessageHandler>(new[] { "second.routing.key", "third.routing.key" });
 ```
 
-You can register it in two modes - **singleton** or **transient** using `AddMessageHandlerSingleton` or `AddMessageHandlerTransient` methods respectively.
+You can also use **pattern matching** in routes where `*` (star) can substitute for exactly one word and `#` (hash) can substitute for zero or more words.
 
 ```c#
 services.AddRabbitMqClient(clientConfiguration)
     .AddExchange("ExchangeName", isConsuming: true, exchangeConfiguration)
-    .AddMessageHandlerTransient<CustomMessageHandler>(new[] { "first.routing.key", "second.routing.key", "third.routing.key" });
+    .AddMessageHandlerSingleton<CustomMessageHandler>("*.routing.*");
+    .AddMessageHandlerSingleton<AnotherCustomMessageHandler>(new[] { "#.key", "third.*" });
 ```
 
-If it is necessary you can also register multiple message handler at once.
+You are also allowed to specify the exact exchange which will be "listened" by message handler with the given routing key (or pattern).
 
 ```c#
 services.AddRabbitMqClient(clientConfiguration)
     .AddExchange("ExchangeName", isConsuming: true, exchangeConfiguration)
-    .AddMessageHandlerTransient<CustomMessageHandler>("first.routing.key")
-    .AddMessageHandlerTransient<AnotherCustomMessageHandler>("second.routing.key");
+    .AddMessageHandlerSingleton<CustomMessageHandler>("*.*.*", "ExchangeName");
+    .AddMessageHandlerSingleton<AnotherCustomMessageHandler>("routing.key", "ExchangeName");
+```
+
+You can register it in two modes, **singleton** or **transient**, using `AddMessageHandlerSingleton` or `AddMessageHandlerTransient` methods respectively.
+
+```c#
+services.AddRabbitMqClient(clientConfiguration)
+    .AddExchange("ExchangeName", isConsuming: true, exchangeConfiguration)
+    .AddMessageHandlerTransient<CustomMessageHandler>(new[] { "#.key", "third.*" });
 ```
 
 You can also set multiple message handlers for managing messages received by one routing key. This case can happen when you want to divide responsibilities between services (e.g. one contains business logic, and the other writes messages in the database).
@@ -200,8 +210,8 @@ public class CustomMessageHandler : IMessageHandler
 }
 ```
 
-The only exception is `IQueueService`, you can't inject it because of the appearance of cyclic dependencies. If you want to use an instance of `IQueueService` (e.g. handle one message and send another) use `INonCyclicMessageHandler`.
-`INonCyclicMessageHandler` can be registered the same way as `IMessageHandler`. There are similar semantic methods for adding it in **singleton** or **transient** mode. 
+The only exception is `IQueueService`. You can't inject it inside a message handler because of the appearance of cyclic dependencies. If you want to use an instance of `IQueueService` (e.g. handle one message and send another) use `INonCyclicMessageHandler`.
+`INonCyclicMessageHandler` can be registered the same way as `IMessageHandler`. There are similar semantic methods for adding it in **singleton** or **transient** modes.
 
 ```c#
 services.AddRabbitMqClient(clientConfiguration)
@@ -232,8 +242,8 @@ public class CustomNonCyclicMessageHandler : INonCyclicMessageHandler
 
 ### Asynchronous message handlers
 
-`IMessageHandler` and `INonCyclicMessageHandler` work synchronously, but if you want an async version then use `IAsyncMessageHandler` and `IAsyncNonCyclicMessageHandler`.
-There are extension methods that allows you to register it the same way as synchronous ones in **singleton** or **transient** modes.
+`IMessageHandler` and `INonCyclicMessageHandler` work synchronously, but if you want to use an async technology then use `IAsyncMessageHandler` and `IAsyncNonCyclicMessageHandler`.
+There are extension methods that allow you to register it the same way as synchronous ones in **singleton** or **transient** modes.
 
 ```c#
 services.AddRabbitMqClient(clientConfiguration)
@@ -288,11 +298,11 @@ So you can use async/await power inside your message handler.
 
 The message handling process is organized as follows:
 
-- `IQueueMessage` receives a message as a byte array and decodes it in UTF8 string.
-- `IQueueMessage` checks if there are any message handlers in collections of `IMessageHandler`, `IAsyncMessageHandler`, `INonCyclicMessageHandler` and `IAsyncNonCyclicMessageHandler` instances and forwards a message to them.
-- All subscribed message handlers (`IMessageHandler`, `IAsyncMessageHandler`, `INonCyclicMessageHandler`, `IAsyncNonCyclicMessageHandler`) process the message.
-- `IQueueMessage` acknowledges the message by its `DeliveryTag`.
-- If any exception occurs `IQueueMessage` acknowledges the message anyway and checks if the message has to be re-send. If exchange option `RequeueFailedMessages` is set `true` then `IQueueMessage` 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).
+- `IQueueMessage` receives a message and delegates it to the `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 collections 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.
+- `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 `"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)

readme.md

@@ -110,6 +110,16 @@ class Program
 You have to configure everything almost the same way as you have already done with producer. The main differences are that you need to declare (configure) consumption exchange calling `AddConsumptionExchange` instead of production exchange. For detailed information about difference in exchange declarations you may want to see the [documentation](./docs/exchange-configuration.md).
 The other important part is adding custom message handlers by implementing `IMessageHandler` interface and calling `AddMessageHandlerSingleton<T>` or `AddMessageHandlerTransient<T>` methods. `IMessageHandler` is a simple subscriber, which receives messages from a queue by selected routing key. You are allowed to set multiple message handlers for one routing key (e.g. one is writing it in a database, and the other does the business logic).
 
+You can also use pattern matching while adding message handlers where `*` (star) can substitute for exactly one word and `#` (hash) can substitute for zero or more words.
+You are also allowed to specify the exact exchange which will be "listened" by the message handler with the given routing key (or a pattern).
+
+```c#
+services.AddRabbitMqClient(rabbitMqSection)
+    .AddConsumptionExchange("exchange.name", exchangeSection)
+    .AddMessageHandlerSingleton<CustomMessageHandler>("*.*.key")
+    .AddMessageHandlerSingleton<AnotherCustomMessageHandler>("#", "exchange.name");
+```
+
 The very last step is to start "listening" (consuming) by simply calling `StartConsuming` method of `IQueueService`. After that you will start getting messages, and you can handle them in any way you want.
 
 Message handler example.