Table of Contents

Quick Start

This guide walks you through a minimal end-to-end example: publishing an event from a Client application and consuming it in a Microservice. By the end you will have a working CarrotMQ setup you can build on.

For this quick start example, we will create 3 separate projects:

  • Dto project: Library project containing the event and endpoint definitions as C# classes.
  • Microservice project: Console application that will consume the events.
  • Client project: Console application that will publish the events.
DtoClientMicroserviceCarrotMQ.CoreCarrotMQ.RabbitMQ

Dto Project

For the Dto project, create a .NET 9 Class Library project. Inside this project, we will define the endpoints and events.

This project should reference the CarrotMQ.Core nuget package.

Defining endpoints

public class MyExchange : ExchangeEndPoint
{
    public MyExchange() : base("my-exchange")
    {
    }
}

public class MyQueue : QueueEndPoint
{
    public MyQueue() : base("my-queue")
    {
    }
}

Defining an event

public class MyEvent : IEvent<MyEvent, MyExchange>
{
    public string Message { get; set; }
}

Microservice Project

For the microservice project, create a .NET 9 console project.

This project should reference the CarrotMQ.RabbitMQ nuget package and the Dto project.

Defining a handler

Inside the microservice project, create the handler class that will handle your event.

public class MyEventHandler : EventHandlerBase<MyEvent>
{
    private readonly ILogger<MyEventHandler> _logger;

    public MyEventHandler(ILogger<MyEventHandler> logger)
    {
        _logger = logger;
    }

    public override async Task<IHandlerResult> HandleAsync(MyEvent message, ConsumerContext consumerContext, CancellationToken cancellationToken)
    {
        _logger.LogInformation(message.Message);

        await Task.Delay(100, cancellationToken).ConfigureAwait(false); // Do something with the event 

        return Ok();
    }
}

Bootstrapping the service

In the Program.cs of your microservice project, configure CarrotMQ for RabbitMQ.

internal class Program
{
    private static async Task Main(string[] args)
    {
        var appBuilder = new HostApplicationBuilder();

        appBuilder.Services.AddCarrotMqRabbitMq(
            builder =>
            {
                builder.ConfigureBrokerConnection(
                    configureOptions: options =>
                    {
                        // Configure the broker connection for your rabbitMq instance (can also be defined in the appsettings)
                        options.UserName = "TestUser";
                        options.Password = "MySuperPassword";
                        options.BrokerEndPoints = [new Uri("amqp://localhost:5672")];
                        options.VHost = "/";
                        options.ServiceName = "CarrotMQ.Demo";
                    });

                // Define the exchange and queue (will be created on startup)
                DirectExchangeBuilder exchange = builder.Exchanges.AddDirect<MyExchange>();
                QuorumQueueBuilder queue = builder.Queues.AddQuorum<MyQueue>()
                    .WithConsumer(); // register a consumer

                // Register the event handler
                builder.Handlers.AddEvent<MyEventHandler, MyEvent>()
                    .BindTo(exchange, queue); // Create the binding from the exchange to the queue with the event name as routing key

                // Start the service as hosted service --> this will start the consumers when starting the host and will continue until the service is stopped
                builder.StartAsHostedService();
            });

        IHost host = appBuilder.Build();

        await host.RunAsync().ConfigureAwait(false);
    }
}

Client Project

For the client project, create a .NET 9 console project (this could be any project type you can run).

This project should also reference the CarrotMQ.RabbitMQ nuget package and the Dto project.

The configuration is similar to the microservice project without creating exchanges, queues, and registering consumers:

internal class Program
{
    private static async Task Main(string[] args)
    {
        var appBuilder = new HostApplicationBuilder();

        appBuilder.Services.AddCarrotMqRabbitMq(
            builder =>
            {
                builder.ConfigureBrokerConnection(
                    configureOptions: options =>
                    {
                        // Configure the broker connection for your rabbitMq instance (can also be defined in the appsettings)
                        options.UserName = "TestUser";
                        options.Password = "MySuperPassword";
                        options.BrokerEndPoints = [new Uri("amqp://localhost:5672")];
                        options.VHost = "/";
                        options.ServiceName = "CarrotMQ.Demo";
                    });
            });

        IHost host = appBuilder.Build();

        await host.StartAsync().ConfigureAwait(false);

        // Get the configured ICarrotClient from the DI
        var carrotClient = host.Services.GetRequiredService<ICarrotClient>();

        // Publish an event over RabbitMQ
        await carrotClient.PublishAsync(new MyEvent { Message = "Hello World" }).ConfigureAwait(false);

        await host.StopAsync().ConfigureAwait(false);
    }
}

Here we directly get the ICarrotClient out of the ServiceCollection, in a real application you can let the DI inject the ICarrotClient interface in your services.

Next Steps

Edit this page