Set up RabbitMQ in the AppHost

This article is the reference for the Aspire RabbitMQ Hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.mts — that you use to model a RabbitMQ server resource in your AppHost project.

If you’re new to the RabbitMQ integration, start with the Get started with RabbitMQ integrations guide. For how consuming apps read the connection information this page exposes, see Connect to RabbitMQ.

Installation

To start building an Aspire app that uses RabbitMQ, install the 📦 Aspire.Hosting.RabbitMQ NuGet package:

C#

Terminal

aspire add rabbitmq

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package Aspire.Hosting.RabbitMQ@*

XML — AppHost.csproj

<PackageReference Include="Aspire.Hosting.RabbitMQ" Version="*" />

TypeScript

Terminal

aspire add rabbitmq

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the RabbitMQ hosting integration package:

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.RabbitMQ": "13.4.0"
  }
}

Tip

If you’d rather connect to an existing RabbitMQ server, see Connect to an existing RabbitMQ instance below.

Add RabbitMQ server resource

Once you’ve installed the hosting integration in your AppHost project, you can add a RabbitMQ server resource as shown in the following examples:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(rabbitmq);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const rabbitmq = await builder.addRabbitMQ("messaging");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(rabbitmq);

// After adding all resources, run the app...

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.io/library/rabbitmq image, it creates a new RabbitMQ server instance on your local machine.

2. The RabbitMQ server resource includes default credentials with a username of "guest" and a randomly generated password using the CreateDefaultPasswordParameter method.

3. The AppHost reference call configures a connection in the consuming project named after the referenced RabbitMQ resource, such as messaging in the preceding example.

Note

When you reference a RabbitMQ resource from the AppHost, Aspire makes several properties available to the consuming project, such as connection URIs, hostnames, port numbers, and credentials. For a complete list of these properties and per-language connection examples, see Connect to RabbitMQ.

Add RabbitMQ server resource with data volume

Add a data volume to the RabbitMQ server resource as shown in the following examples:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
    .WithDataVolume(isReadOnly: false);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(rabbitmq);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const rabbitmq = await builder.addRabbitMQ("messaging");
await rabbitmq.withDataVolume({ isReadOnly: false });

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(rabbitmq);

// After adding all resources, run the app...

The data volume is used to persist RabbitMQ server data outside the lifecycle of its container. The data volume is mounted at the /var/lib/rabbitmq path in the RabbitMQ server container and when a name parameter isn’t provided, the name is generated at random. For more information on data volumes and details on why they’re preferred over bind mounts, see Docker docs: Volumes.

Add RabbitMQ server resource with data bind mount

Add a data bind mount to the RabbitMQ server resource as shown in the following examples:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
    .WithDataBindMount(
        source: "/RabbitMQ/Data",
        isReadOnly: false);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(rabbitmq);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const rabbitmq = await builder.addRabbitMQ("messaging");
await rabbitmq.withDataBindMount("/RabbitMQ/Data", { isReadOnly: false });

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(rabbitmq);

// After adding all resources, run the app...

Note

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

Data bind mounts rely on the host machine’s filesystem to persist RabbitMQ server data across container restarts. The data bind mount is mounted at the C:\RabbitMQ\Data on Windows (or /RabbitMQ/Data on Unix) path on the host machine in the RabbitMQ server container. For more information on data bind mounts, see Docker docs: Bind mounts.

Add RabbitMQ server resource with parameters

When you want to explicitly provide the username and password used by the container image, you can provide these credentials as parameters. Consider the following alternative examples:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var rabbitmq = builder.AddRabbitMQ("messaging", username, password);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(rabbitmq);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const userName = await builder.addParameter("username", { secret: true });
const password = await builder.addParameter("password", { secret: true });

const rabbitmq = await builder.addRabbitMQ("messaging", { userName, password });

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(rabbitmq);

// After adding all resources, run the app...

When no password parameter is provided, Aspire generates a strong password automatically using the CreateDefaultPasswordParameter method.

Add RabbitMQ server resource with management plugin

To add the RabbitMQ management plugin as a sub-resource, call WithManagementPlugin (or withManagementPlugin). You’ll need the credentials you configured to log in to the management UI:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var rabbitmq = builder.AddRabbitMQ("messaging", username, password)
    .WithManagementPlugin();

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(rabbitmq);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const userName = await builder.addParameter("username", { secret: true });
const password = await builder.addParameter("password", { secret: true });

const rabbitmq = await builder.addRabbitMQ("messaging", { userName, password });
await rabbitmq.withManagementPlugin();

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(rabbitmq);

// After adding all resources, run the app...

The RabbitMQ management plugin provides an HTTP-based API for management and monitoring of your RabbitMQ server. Aspire adds another container image using the docker.io/library/rabbitmq management variant to the AppHost that runs the management plugin on port 15672 by default. You can access the management UI from the Aspire dashboard by selecting the endpoint for your RabbitMQ resource.

To configure a custom host port for the management plugin, pass the port option:

C#

C# — AppHost.cs

var rabbitmq = builder.AddRabbitMQ("messaging")
    .WithManagementPlugin(port: 15672);

TypeScript

TypeScript — apphost.mts

await rabbitmq.withManagementPlugin({ port: 15672 });

Pass custom environment variables

By default, Aspire injects the RabbitMQ connection information using variable names derived from the resource name (for example, MESSAGING_URI, MESSAGING_HOST, MESSAGING_PORT, MESSAGING_USERNAME, MESSAGING_PASSWORD). If your consuming app expects a different set of environment variable names, pass individual connection properties from the AppHost:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging");

var app = builder.AddExecutable("my-app", "node", "app.js", ".")
    .WithReference(rabbitmq)
    .WithEnvironment(context =>
    {
        context.EnvironmentVariables["RABBITMQ_HOST"] = rabbitmq.Resource.PrimaryEndpoint.Property(EndpointProperty.Host);
        context.EnvironmentVariables["RABBITMQ_PORT"] = rabbitmq.Resource.PrimaryEndpoint.Property(EndpointProperty.Port);
        context.EnvironmentVariables["RABBITMQ_USER"] = rabbitmq.Resource.UserNameParameter;
        context.EnvironmentVariables["RABBITMQ_PASSWORD"] = rabbitmq.Resource.PasswordParameter;
    });

builder.Build().Run();

TypeScript

TypeScript — apphost.mts

import { createBuilder, EndpointProperty } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const rabbitmq = await builder.addRabbitMQ("messaging");
const rabbitmqEndpoint = await rabbitmq.getEndpoint("tcp");
const rabbitmqHost = await rabbitmqEndpoint.property(EndpointProperty.Host);
const rabbitmqPort = await rabbitmqEndpoint.property(EndpointProperty.Port);

await builder.addNodeApp("my-app", "./app", "index.js")
    .withReference(rabbitmq)
    .withEnvironment("RABBITMQ_HOST", rabbitmqHost)
    .withEnvironment("RABBITMQ_PORT", rabbitmqPort)
    .withEnvironment("RABBITMQ_USER", await rabbitmq.userNameParameter())
    .withEnvironment("RABBITMQ_PASSWORD", await rabbitmq.passwordParameter());

await builder.build().run();

Connect to an existing RabbitMQ instance

To reference an externally managed RabbitMQ instance instead of running one as a container, use AddConnectionString:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddConnectionString("messaging");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(rabbitmq);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const rabbitmq = await builder.addConnectionString("messaging");

await builder.addNodeApp("my-app", "./app", "index.js")
    .withReference(rabbitmq);

// After adding all resources, run the app...
await builder.build().run();

With AddConnectionString and addConnectionString, Aspire resolves messaging from ConnectionStrings:messaging (or environment variable ConnectionStrings__messaging) in the AppHost configuration. Consuming apps receive that value as a single connection string, not deconstructed RabbitMQ resource-specific connection-property variables such as MESSAGING_URI, MESSAGING_HOST, or MESSAGING_PORT.

Connection properties

For the full reference of RabbitMQ resource connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to RabbitMQ.

RabbitMQ 4.3 queue declaration requirements

Starting with Aspire 13.4, the default RabbitMQ container image used by AddRabbitMQ is 4.3. RabbitMQ 4.3 disables the deprecated transient_nonexcl_queues feature by default. Declaring a queue that is simultaneously non-durable (transient) and non-exclusive is rejected by the broker with AMQP error 541 (INTERNAL_ERROR - Feature 'transient_nonexcl_queues' is deprecated.).

If your application declares such queues, switch to one of the supported patterns:

• Durable (durable: true) — the queue definition survives broker restarts.
• Transient exclusive (exclusive: true) — the queue is auto-deleted when the declaring connection closes.
• Durable with a queue TTL — for short-lived queues whose definition survives a restart but whose contents expire on a schedule.

For upstream details, see the RabbitMQ 4.3.0 release notes.

Note

Neither the Aspire RabbitMQ hosting integration (Aspire.Hosting.RabbitMQ) nor the client integration (Aspire.RabbitMQ.Client) declares queues for you. The hosting integration models and runs the RabbitMQ broker as a resource and exposes a connection string; the client integration registers an IConnection and wires up DI, configuration, telemetry, and health checks. Queue topology is entirely owned by your application code, so any queue declarations your app makes must comply with the RabbitMQ 4.3 requirements above.

Hosting integration health checks

The RabbitMQ hosting integration automatically adds a health check for the RabbitMQ server resource. The health check verifies that the RabbitMQ server is running and that a connection can be established to it.

The hosting integration relies on the 📦 AspNetCore.HealthChecks.Rabbitmq NuGet package.