Added changelog

Author: Anton Vorontsov

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,8 +2,8 @@
 
 ### Starting a consumer
 
-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.
+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 looks like this.
 
@@ -27,7 +27,7 @@ public class Startup
 }
 ```
 
-You can register an `IHostedService` and inject the instance of the `IQueueService` into it.
+You can register `IHostedService` and inject an instance of `IQueueService` into it.
 
 ```c#
 services.AddSingleton<IHostedService, ConsumingService>();
@@ -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#
@@ -134,7 +134,8 @@ public class Startup
 
 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. If it is necessary you can also register multiple message handler at once.
+`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)
@@ -151,7 +152,7 @@ services.AddRabbitMqClient(clientConfiguration)
     .AddMessageHandlerSingleton<AnotherCustomMessageHandler>(new[] { "#.key", "third.*" });
 ```
 
-You are also allowed to specify the exact exchange which will be "listened" by message handler with the given routing key (or pattern).
+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)
@@ -178,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
@@ -192,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
@@ -210,7 +211,7 @@ public class CustomMessageHandler : IMessageHandler
 }
 ```
 
-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`.
+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#
@@ -298,7 +299,7 @@ So you can use async/await power inside your message handler.
 
 The message handling process is organized as follows:
 
-- `IQueueMessage` receives a message and delegates it to the `IMessageHandlingService`.
+- `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`.

docs/message-production.md

@@ -5,6 +5,7 @@
 `IQueueService` represents a service that handles all the work of sending and receiving messages. You can inject `IQueueService` wherever you want in order to use it.
 
 It can be a custom service or a controller.
+
 ```c#
 [Route("api/[controller]")]
 public class HomeController : Controller
@@ -42,9 +43,10 @@ public static class Program
 }
 ```
 
-To publish a message to an exchange, use one of the `IQueueService` sending methods.
+To publish a message to an exchange, use one of `IQueueService` sending methods.
 
 You can send objects using `Send` or `SendAsync` methods. Objects will be serialized into json and sent with `IBasicProperties` where content type set as `"application/json"` and `Persistent` set as `true`. 
+
 ```c#
 var message = new
 {
@@ -66,7 +68,7 @@ await queueService.SendJsonAsync(message, exchangeName: "exchange.name", routing
 ```
 
 If you want to send a message in another format different from json you can use `SendString` methods.
-In this case `IBasicProperties` will be only with `Persistent` property set as `true`, so you can send any string you want (e.g. an XML string).
+In this case `IBasicProperties` will be only with the `Persistent` property set as `true`, so you can send any string you want (e.g. an XML string).
 
 ```c#
 var message = "<?xml version="1.0" encoding="UTF-8"?><message>Hello World!</message>";
@@ -75,7 +77,8 @@ queueService.SendString(message, exchangeName: "exchange.name", routingKey: "rou
 await queueService.SendStringAsync(message, exchangeName: "exchange.name", routingKey: "routing.key");
 ```
 
-And if you want to manage everything by yourself you can use `Send` methods passing message as byte array and `IBasicProperties` as parameters.
+And if you want to manage everything by yourself you can use `Send` methods passing message as a byte array and `IBasicProperties` as parameters.
+
 ```c#
 var properties = queueService.Channel.CreateBasicProperties();
 // Set everything you want.
@@ -87,7 +90,8 @@ queueService.Send(bytes, properties, exchangeName: "exchange.name", routingKey:
 await queueService.SendAsync(bytes, properties, exchangeName: "exchange.name", routingKey: "routing.key");
 ```
 
-You are also allowed to send messages with delay (in seconds). All of the previously listed methods have an overload that takes delay parameter.
+You are also allowed to send messages with delay (in seconds). All of previously listed methods have an overload that takes a `delay` parameter.
+
 ```c#
 // Objects
 queueService.Send(message, exchangeName: "exchange.name", routingKey: "routing.key", secondsDelay: 10);
@@ -107,24 +111,26 @@ await queueService.SendAsync(bytes, properties, exchangeName: "exchange.name", r
 ```
 
 ### Mechanism of sending delayed messages
+
 The implementation of sending deferred (delayed) messages in this project is quite tricky.
 The image below shows a model of the whole process of passing the message from the producer to the consumer.
 ![Model of sending delayed messages](./images/delayed-message-model.png)
 
-**Prerequisites.** Let's say that producer want to send a message to the exchange **"Exchange B"** with a routing key **"routing.key"** and delay in **30 seconds**.
- -  Message goes to the exchange **"Exchange A"** whose responsibility is to manage delaying (storing) the message.
- - After that a queue with a compound name and special arguments is being created. Name consists of three parts: routing key of sent message, word "delayed" and number of seconds delay.
+**Prerequisites.** Let's say that producer want to send a message to the exchange **"Exchange B"** with a routing key **"routing.key"**, and a delay in **30 seconds**.
+ - Message goes to the exchange **"Exchange A"** whose responsibility is to manage delaying (storing) the message.
+ - After that a queue with a compound name and special arguments is being created. Name consists of three parts: the routing key of the sent message, a word "delayed", and a number of delay seconds .
 Queue arguments are as follows.
 ```
 x-dead-letter-exchange : Exchange В
 x-dead-letter-routing-key : routing.key
 x-message-ttl : secondsDelay * 1000
 x-expires : secondsDelay * 1000 + 60000
 ```
- - A message, which gets in that queue, will have a specified ttl (time to live) and an exchange to which the message will be sent after expiration.
+ - A message, which gets in that queue, will have a specified ttl (time to live), and an exchange to which the message will be sent after expiration.
  - That new queue bounds to the **Exchange A**. That queue will be automatically deleted if there are no more messages in it within a minute.
- - Message goes to that queue, waits until expiration and goes in the **"Exchange B"**, which routes it as it should be.
- - Message gets in the destination queue and consumer can retrieve that message.
+ - Message goes to that queue, waits until an expiration moment and goes in the **"Exchange B"**, which routes it as it should be.
+ - Message gets in the destination queue, and the consumer can retrieve that message.
+
+For the exchange configuration see the [Previous page](exchange-configuration.md)
 
-For the exchange configuration see the [Previous page](exchange-configuration.md) <br>
 For message consumption features see the [Next page](message-consumption.md)

docs/rabbit-configuration.md

@@ -1,7 +1,7 @@
 # RabbitMQ configuration
 
-To connect to a RabbitMQ, it is necessary to instantiate an `IQueueService` and configure it to use desired endpoint, credentials and other valuable connection settings.
-`IQueueService` allows clients to configure queues to exchange bindings, and to consume and produce messages in different ways (sync or async, with or without delay). To add `IQueueService` in your application simply use `AddRabbitMqClient` extension method as in the example below.
+To connect to a RabbitMQ server, it is necessary to instantiate `IQueueService` and configure it to use a desired endpoint, credentials and other valuable connection settings.
+`IQueueService` allows clients to configure queues to exchange bindings, and to consume and produce messages in different ways (sync or async, with or without delay). To add `IQueueService` in your application simply use the `AddRabbitMqClient` extension method as in the example below.
 
 ```c#
 public class Startup
@@ -24,7 +24,7 @@ public class Startup
 }
 ```
 
-RabbitMQ client can be configured via configuration section located in the `appsettings.json` file. This configuration section must be of a certain format and down below is an example of all configuration options used in `IQueueService`.
+A RabbitMQ client can be configured via a configuration section located in the `appsettings.json` file. This configuration section must be of a certain format and down below is an example of all configuration options used in `IQueueService`.
 
 ```json
 {
@@ -43,7 +43,7 @@ RabbitMQ client can be configured via configuration section located in the `apps
 }
 ```
 
-RabbitMQ connection can be configured with properties:
+A RabbitMQ connection can be configured with properties:
 - `HostName`  - RabbitMQ server,
 - `HostNames` - collection of RabbitMQ hostnames,
 - `TcpEndpoints` - collection of AMPQ TCP endpoints,
@@ -70,7 +70,7 @@ RabbitMQ connection can be configured with properties:
 }
 ```
 
-For high availability RabbitMQ clusters with multiple nodes you can set hosts collection with `HostNames` option.
+For high availability RabbitMQ clusters with multiple nodes you can set hosts collection with the `HostNames` option.
 
 ```json
 {
@@ -109,9 +109,9 @@ If nodes are running on different hosts with different ports you have an option
 }
 ```
 
-There is an importance of `TcpEndpoints`, `HostNames`, `HostName` options. If all of them are set connection will be created using `TcpEndpoints` option. The second will be option `HostNames` and the `HostName` option is the least important between those three.
+There is an importance of `TcpEndpoints`, `HostNames`, `HostName` options. If all of them are set connection will be created using the `TcpEndpoints` option. The second will be the option `HostNames` and the `HostName` option is the least important between those three.
 
-If `.json` configuration files unacceptable for you there is another `AddRabbitMqClient` extension method that takes manually created `RabbitMqClientOptions` configuration as a parameter. `RabbitMqClientOptions` is the model class used for injecting RabbitMQ client configuration as an `IOtions<T>` instance so properties named the same as in the previous method.
+If `.json` configuration files unacceptable for you there is another `AddRabbitMqClient` extension method that takes manually created `RabbitMqClientOptions` configuration as a parameter. `RabbitMqClientOptions` is the model class used for injecting a RabbitMQ client configuration as an `IOtions<T>` instance so properties named the same as in the previous method.
 
 ```c#
 public class Startup