Merge pull request #20 from AntonyVorontsov/feature/wildcards-docs

Feature/wildcards docs

Author: antonyvorontsov

.github/workflows/dotnetcore.yml

@@ -0,0 +1,18 @@
+name: .NET Core
+
+on: [push]
+
+jobs:
+  workflow:
+
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup .NET Core
+      uses: actions/setup-dotnet@v1
+      with:
+        dotnet-version: 3.1.100
+    - name: Build
+      run: dotnet build --configuration Release
+    - name: Run tests
+      run: dotnet test --configuration Release

docs/changelog.md

@@ -2,6 +2,15 @@
 
 All notable changes to this library will be documented in this file.
 
+## [3.1.1] - 2020-01-20
+
+### Added
+
+- Pattern matching (`WildcardExtensions`) so message handlers can now
+- Extension methods which allow user to set the exact exchange from which messages will be processed by message handlers.
+- `MessageHandlingService` which is responsible for message processing.
+- `WildcardExtensions` and `MessageHandlingService` unit tests.
+
 ## [2.2.1] copy of [3.1.0] - 2019-12-06
 
 ### Added

docs/exchange-configuration.md

@@ -2,8 +2,8 @@
 
 ### Basics
 
-Client applications work with exchanges and queues, and they must be "declared" and "bound" to each other is a certain way before they can be used.
-Queues and exchanges can also be customized by using additional parameters. This library allows to do this routine simply calling `AddExchange` method passing additional parameters to it.
+Client applications work with exchanges and queues which must be "declared" and "bound" to each other in a certain way before they can be used.
+Queues and exchanges can also be customized by using additional parameters. This library allows you to do this routine simply calling the `AddExchange` method passing additional parameters to it.
 You are allowed to configure multiple exchanges with multiple queues bound to them.
 
 Your `Startup` code will look like this.
@@ -57,26 +57,26 @@ And the `appsettings.json` file will be like this.
 }
 ```
 
-The RabbitMQ client configuration section not specified in this example, for more information see the [documentation](rabbit-configuration.md) file.
+The RabbitMQ client configuration section is not specified in this example, for more information see the [documentation](rabbit-configuration.md) file.
 
 Exchanges can be configured with properties:
-- `Type`  - exchange type (direct, topic, fanout). Default value is `"direct"`.
-- `Durable` - durability option. Default value is `true`.
-- `AutoDelete` - option for exchange auto deleting. Default value is `false`.
-- `Arguments` - dictionary of additional arguments. Default value is `null`.
-- `RequeueFailedMessages` - option that specifies behaviour of re-queueing failed messages with delay through dead-letter-exchange. Default value is `true`. Mechanism of sending delayed messages covered in the [documentation](message-production.md).
-- `DeadLetterExchange` - default value for dead-letter-exchange. Default value for dead-letter-exchange name is `"default.dlx.exchange"`.
-- `Queues` - collection of queues bound to the exchange.
+- `Type`  - an exchange type (direct, topic, fanout). The default value is `"direct"`.
+- `Durable` - a durability option. The default value is `true`.
+- `AutoDelete` - an option for exchange auto deleting. The default value is `false`.
+- `Arguments` - a dictionary of additional arguments. The default value is `null`.
+- `RequeueFailedMessages` - an option that specifies behaviour of re-queueing failed messages with certain delay through the dead-letter-exchange. The default value is `true`. The mechanism of sending delayed messages is covered in the [documentation](message-production.md).
+- `DeadLetterExchange` - a value for dead-letter-exchange. The default value for the dead-letter-exchange name is `"default.dlx.exchange"`.
+- `Queues` - a collection of queues bound to the exchange.
 
 Queue options:
-- `Name`  - queue name.
-- `Durable` - durability option. Default value is `true`.
-- `AutoDelete` - option for queue auto deleting. Default value is `false`.
-- `Exclusive` - exclusive option. Default value is `false`.
-- `Arguments` - dictionary of additional [arguments](https://www.rabbitmq.com/queues.html#optional-arguments). Default value is `null`.
-- `RoutingKeys` - collection of routing keys that queue "listens".
+- `Name`  - a queue name.
+- `Durable` - a durability option. The default value is `true`.
+- `AutoDelete` - an option for queue auto deleting. The default value is `false`.
+- `Exclusive` - an exclusive option. The default value is `false`.
+- `Arguments` - a dictionary of additional [arguments](https://www.rabbitmq.com/queues.html#optional-arguments). The default value is `null`.
+- `RoutingKeys` - a collection of routing keys that the queue "listens".
 
-Taking into account all the default values that you can skip configuration will look like this.
+Taking into account all the default values that you can skip, configuration will look like this.
 
 ```json
 {
@@ -92,7 +92,7 @@ Taking into account all the default values that you can skip configuration will
 }
 ```
 
-If you want to use routing keys matching with queue names you can skip `"RoutingKeys"` option and queues will be bound to the exchange by their names.
+If you want to use routing keys matching with queue names you can skip the `"RoutingKeys"` option and queues will be bound to the exchange by their names.
 
 ```json
 {
@@ -184,5 +184,6 @@ services.AddRabbitMqClient(clientConfiguration)
     .AddConsumptionExchange("ConsumptionExchange", exchangeConfiguration);
 ```
 
-For the RabbitMQ client configuration see the [Previous page](rabbit-configuration.md) <br>
+For the RabbitMQ client configuration see the [Previous page](rabbit-configuration.md)
+
 For message production features see the [Next page](message-production.md)

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 the `StartConsuming` method of `IQueueService`.
+Consumption exchanges will work only in a message-production mode if the `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 `IHostedService` and inject an instance of `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
@@ -108,7 +108,7 @@ public class Worker : BackgroundService
 
 The second step without which receiving messages does not make sense - configuration of message handling services. If there are no message handlers then received messages will not be processed.
 
-Message handlers are classes that implement `IMessageHandler` interface (or a few others) and contain functionality including error handling for processing messages.
+Message handlers are classes that implement the `IMessageHandler` interface (or a few others) and contain functionality (including error handling) for processing messages.
 You can register `IMessageHandler` in your `Startup` like this.
 
 ```c#
@@ -132,30 +132,41 @@ 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 the 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>("first.routing.key");
+    .AddMessageHandlerSingleton<AnotherCustomMessageHandler>(new[] { "second.routing.key", "third.routing.key" });
+```
+
+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.
 
-`IMessageHandler` implementation will "listen" for messages by specified routing key, or a collection of routing keys.
 ```c#
 services.AddRabbitMqClient(clientConfiguration)
     .AddExchange("ExchangeName", isConsuming: true, exchangeConfiguration)
-    .AddMessageHandlerSingleton<CustomMessageHandler>(new[] { "first.routing.key", "second.routing.key", "third.routing.key" });
+    .AddMessageHandlerSingleton<CustomMessageHandler>("*.routing.*");
+    .AddMessageHandlerSingleton<AnotherCustomMessageHandler>(new[] { "#.key", "third.*" });
 ```
 
-You can register it in two modes - **singleton** or **transient** using `AddMessageHandlerSingleton` or `AddMessageHandlerTransient` methods respectively.
+You are also allowed to specify the exact exchange which will be "listened" by a message handler with the given routing key (or a pattern).
 
 ```c#
 services.AddRabbitMqClient(clientConfiguration)
     .AddExchange("ExchangeName", isConsuming: true, exchangeConfiguration)
-    .AddMessageHandlerTransient<CustomMessageHandler>(new[] { "first.routing.key", "second.routing.key", "third.routing.key" });
+    .AddMessageHandlerSingleton<CustomMessageHandler>("*.*.*", "ExchangeName");
+    .AddMessageHandlerSingleton<AnotherCustomMessageHandler>("routing.key", "ExchangeName");
 ```
 
-If it is necessary you can also register multiple message handler at once.
+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>("first.routing.key")
-    .AddMessageHandlerTransient<AnotherCustomMessageHandler>("second.routing.key");
+    .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).
@@ -168,8 +179,8 @@ services.AddRabbitMqClient(clientConfiguration)
     .AddMessageHandlerSingleton<OneMoreCustomMessageHandler>("first.routing.key");
 ```
 
-`IMessageHandler` consists of one method `Handle` that gets a message in string format. You can deserialize it (if it is a json message) or handle a raw value.
-Thus, message handler will look like this.
+`IMessageHandler` consists of one method `Handle` that gets a message in a string format. You can deserialize it (if it is a json message) or handle a raw value.
+Thus, a message handler will look like this.
 
 ```c#
 public class CustomMessageHandler : IMessageHandler
@@ -182,7 +193,7 @@ public class CustomMessageHandler : IMessageHandler
 }
 ```
 
-You can also inject services inside `IMessageHandler` constructor.
+You can also inject services inside the `IMessageHandler` constructor.
 
 ```c#
 public class CustomMessageHandler : IMessageHandler
@@ -200,8 +211,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 the `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 +243,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 +299,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 `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)