If you are used to handling connections to a relational database like SQL Server, you might find the way EasyNetQ handles connections a little odd. Communication with a relational database is always initiated by the client. The client opens a connection, issues an SQL command, processes the results if necessary, and then closes the connection. The general advice is that you should hold an open connection for as little time as possible and leave the connection pooling to the API.

Talking to a message broker such as RabbitMQ is a little different because the connection tends to last the lifetime of the application. Typically you will open a connection, create a subscription, and then wait for any messages to arrive on the open connection. EasyNetQ does not assume that the broker will be available at all times. Instead, it employs a lazy connection approach, polling the given endpoint on a background thread until it can connect. If the server disconnects for any reason (maybe a network fault, maybe the RabbitMQ server itself has been bounced), EasyNetQ will revert to polling the endpoint until it can reconnect.

Standard practice is to create a single IBus instance for the lifetime of your application. Dispose it when your application closes.

A lazy connection to a RabbitMQ server is represented by an IBus interface. Most EasyNetQ operations are methods on IBus.

With the release of EasyNetQ v8, creating an IBus instance(connect to a RabbitMQ broker) has changed.

Creating an IBus instance leverages Dependency Injection (DI) in v8.x:

var serviceCollection = new ServiceCollection();
serviceCollection.AddEasyNetQ("host=myServer;virtualHost=myVirtualHost;username=mike;password=topsecret")
                 .UseSystemTextJson();

using var provider = serviceCollection.BuildServiceProvider();
var bus = provider.GetRequiredService<IBus>();

Explanation

1. Service Collection: An instance of ServiceCollection is created.

   var serviceCollection = new ServiceCollection();

2. AddEasyNetQ: EasyNetQ services are added to the service collection using the connection string.

   serviceCollection.AddEasyNetQ("host=myServer;virtualHost=myVirtualHost;username=mike;password=topsecret")
                    .UseSystemTextJson();

• AddEasyNetQ: Registers EasyNetQ services.
• UseSystemTextJson(): Configures EasyNetQ to use System.Text.Json for message serialization.

3. Build Service Provider: The service provider is built from the service collection.

   using var provider = serviceCollection.BuildServiceProvider();

• using var: Ensures that the ServiceProvider instance is disposed of correctly when it goes out of scope and handles disposal whenever an error or exception occurs within the using block.

4. Retrieve IBus Instance: The IBus instance is retrieved from the service provider.

   var bus = provider.GetRequiredService<IBus>();

To create an IBus instance in v7.x:

var bus = RabbitHutch.CreateBus("host=myServer;virtualHost=myVirtualHost;username=mike;password=topsecret");

For both v7 and v8, the connection string is made up of key/value pairs in the format key=value, each one separated by a semicolon (;). The only required field is 'host'.

The possible connection string values are:

• host (e.g. host=localhost or host=192.168.2.56 or host=myhost.mydomain.com) this field is required. To specify the port you want to connect to, you can use the standard format host:port (e.g. host=myhost.com:5673). If you omit the port number, the default AMQP port is used (5672). To connect to a RabbitMQ cluster, specify each cluster node separated by commas (e.g. host=myhost1.com,myhost2.com,myhost3.com). See Cluster Support for more details.
• virtualHost (e.g. virtualHost=myVirtualHost) default is the default virtual host '/'
• username (e.g. username=mike) default is 'guest' (for non 'localhost' host you need other user than 'guest')
• password (e.g. password=mysecret) default is 'guest'
• requestedHeartbeat (e.g. requestedHeartbeat=10) default is 10 seconds. Set to zero for no heartbeat.
• prefetchcount (e.g. prefetchcount=1) default is 50. This is the number of messages that will be delivered by RabbitMQ before an ack is sent by EasyNetQ. Set to 0 for infinite prefetch (not recommended). Set to 1 for fair work balancing among a farm of consumers.
• publisherConfirms (e.g. publisherConfirms=true) default is false. This turns on Publisher Confirms.
• persistentMessages (e.g. persistentMessages=false) default is true. This determines how the delivery_mode in basic.properties is set when a message is published. false=1, true=2. When set to true, messages will be persisted to disk by RabbitMQ and survive a server restart. Performance gains can be expected when set to false.
• product (e.g. product=My really important service) was introduced in EasyNetQ 0.27.3. default value is the name of the executable which instantiates the bus. The value entered here will show up in the administrative interface for RabbitMQ.
• platform (e.g. platform=my.fully.qualified.domain.name) was introduced in EasyNetQ 0.27.3. default value is the hostname of the machine running the client process instantiating the bus. The value entered here will show up in the administrative interface for RabbitMQ.
• timeout (e.g timeout=60) default is 10 seconds. Was introduced in EasyNetQ 0.17. Parsed to type System.UInt16. Range from 0 to 65535. Format is in seconds. For infinite timeout please use 0. Throws System.TimeoutException when value exceeded.
• ssl=true Allows enabling ssl in vanilla connection string. This also works with multiple hosts. This was introduced in EasyNetQ 7.5.2.

EasyNetQ is known for using the Newtonsoft.Json library as its default JSON serialiser. However, starting from EasyNetQ v7, Newtonsoft.Json has been removed from its dependencies. To address this change, you may need to manually add Newtonsoft.Json or utilize the built-in System.Text.Json library. If you prefer to use System.Text.Json, follow these two steps:

1. Install the EasyNetQ.Serialization.SystemTextJson package using this command:

   dotnet add package EasyNetQ.Serialization.SystemTextJson

   Or

   PM> Install-Package EasyNetQ.Serialization.SystemTextJson

2. Initialise your EasyNetQ using the code below, adhering to .NET's built-in Dependency Injection (DI):

   RabbitHutch.CreateBus("host=localhost", s => s.EnableSystemTextJson());
   

By adding the EasyNetQ.Serialization.SystemTextJson package and enabling the System.Text.Json serializer through the IBus initialization code, you can seamlessly transition to using System.Text.Json while maintaining EasyNetQ's capabilities in your .NET Core application.

To close the connection, simply dispose the bus like this:

bus.Dispose();

This will close the connection, channels, consumers and all other resources used by EasyNetQ.

In EasyNetQ v8, Newtonsoft.Json is no longer a dependency, and System.Text.Json serialization is enabled by default when configuring EasyNetQ through Dependency Injection (DI).

Closing the Connection:

To close the connection and release resources used by EasyNetQ, simply utilize the using keyword when creating your ServiceProvider. This approach automatically disposes of resources once they are no longer needed, ensuring proper cleanup even if errors or exceptions occur within the using block.

Example:

var serviceCollection = new ServiceCollection();
serviceCollection.AddEasyNetQ("host=myServer;virtualHost=myVirtualHost;username=mike;password=topsecret")
                 .UseSystemTextJson();

using var provider = serviceCollection.BuildServiceProvider();
// Use IBus instance obtained from provider as needed

// No explicit call to bus.Dispose() is necessary in EasyNetQ v8