title | description | ms.topic | ms.date |
---|---|---|---|
.NET Aspire RabbitMQ component |
Learn how to use the .NET Aspire RabbitMQ client message-broker component. |
how-to |
06/05/2024 |
In this article, you learn how to use the .NET Aspire RabbitMQ client message-broker. The Aspire.RabbitMQ.Client
library is used to register an IConnection in the dependency injection (DI) container for connecting to a RabbitMQ server. It enables corresponding health check, logging and telemetry.
To get started with the .NET Aspire RabbitMQ component, install the Aspire.RabbitMQ.Client NuGet package.
dotnet add package Aspire.RabbitMQ.Client
<PackageReference Include="Aspire.RabbitMQ.Client"
Version="[SelectVersion]" />
For more information, see dotnet add package or Manage package dependencies in .NET applications.
In the :::no-loc text="Program.cs"::: file of your component-consuming project, call the xref:Microsoft.Extensions.Hosting.AspireRabbitMQExtensions.AddRabbitMQClient%2A extension method to register an IConnection
for use via the dependency injection container. The method takes a connection name parameter.
builder.AddRabbitMQClient("messaging");
You can then retrieve the IConnection
instance using dependency injection. For example, to retrieve the connection from an example service:
public class ExampleService(IConnection connection)
{
// Use connection...
}
To model the RabbitMQ resource in the app host, install the Aspire.Hosting.RabbitMQ NuGet package.
dotnet add package Aspire.Hosting.RabbitMQ
<PackageReference Include="Aspire.Hosting.RabbitMQ"
Version="[SelectVersion]" />
In your app host project, register a RabbitMQ server and consume the connection using the following methods, such as xref:Aspire.Hosting.RabbitMQBuilderExtensions.AddRabbitMQ%2A:
var builder = DistributedApplication.CreateBuilder(args);
var messaging = builder.AddRabbitMQ("messaging");
builder.AddProject<Projects.ExampleProject>()
.WithReference(messaging);
The xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A method configures a connection in the ExampleProject
project named messaging
.
When you want to explicitly provide the username and password, you can provide those as parameters. Consider the following alternative example:
var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);
var messaging = builder.AddRabbitMQ("messaging", username, password);
// Service consumption
builder.AddProject<Projects.ExampleProject>()
.WithReference(messaging);
For more information, see External parameters.
The .NET Aspire RabbitMQ component provides multiple options to configure the connection based on the requirements and conventions of your project.
When using a connection string from the ConnectionStrings
configuration section, you can provide the name of the connection string when calling builder.AddRabbitMQClient
:
builder.AddRabbitMQClient("RabbitMQConnection");
And then the connection string will be retrieved from the ConnectionStrings
configuration section:
{
"ConnectionStrings": {
"RabbitMQConnection": "amqp://username:password@localhost:5672"
}
}
For more information on how to format this connection string, see the RabbitMQ URI specification docs.
The .NET Aspire RabbitMQ component supports xref:Microsoft.Extensions.Configuration. It loads the RabbitMQClientSettings
from configuration by using the Aspire:RabbitMQ:Client
key. Example :::no-loc text="appsettings.json"::: that configures some of the options:
{
"Aspire": {
"RabbitMQ": {
"Client": {
"DisableHealthChecks": true
}
}
}
}
Also you can pass the Action<RabbitMQClientSettings> configureSettings
delegate to set up some or all the options inline, for example to disable health checks from code:
builder.AddRabbitMQClient(
"messaging",
static settings => settings.DisableHealthChecks = true);
You can also set up the IConnectionFactory using the Action<IConnectionFactory> configureConnectionFactory
delegate parameter of the AddRabbitMQClient
method. For example to set the client provided name for connections:
builder.AddRabbitMQClient(
"messaging",
static configureConnectionFactory:
factory => factory.ClientProvidedName = "MyApp");
[!INCLUDE component-health-checks]
The .NET Aspire RabbitMQ component handles the following:
- Adds the health check when xref:Aspire.RabbitMQ.Client.RabbitMQClientSettings.DisableHealthChecks?displayProperty=nameWithType is
true
, which attempts to connect to and create a channel on the RabbitMQ server. - Integrates with the
/health
HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic.
[!INCLUDE component-observability-and-telemetry]
The .NET Aspire RabbitMQ component uses the following log categories:
RabbitMQ.Client
The .NET Aspire RabbitMQ component will emit the following tracing activities using OpenTelemetry:
- "Aspire.RabbitMQ.Client"
The .NET Aspire RabbitMQ component currently doesn't support metrics by default. If that changes in the future, this section will be updated to reflect those changes.