# 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`](/get-started/app-host/) project.
If you're new to the RabbitMQ integration, start with the [Get started with RabbitMQ integrations](/integrations/messaging/rabbitmq/rabbitmq-get-started/) guide. For how consuming apps read the connection information this page exposes, see [Connect to RabbitMQ](../rabbitmq-connect/).
## Installation
To start building an Aspire app that uses RabbitMQ, install the [📦 Aspire.Hosting.RabbitMQ](https://www.nuget.org/packages/Aspire.Hosting.RabbitMQ) NuGet package:
```bash title="Terminal"
aspire add rabbitmq
```
Learn more about [`aspire add`](/reference/cli/commands/aspire-add/) in the command reference.
Or, choose a manual installation approach:
```csharp title="C# — AppHost.cs"
#:package Aspire.Hosting.RabbitMQ@*
```
```xml title="XML — AppHost.csproj"
```
```bash title="Terminal"
aspire add rabbitmq
```
Learn more about [`aspire add`](/reference/cli/commands/aspire-add/) in the command reference.
This updates your `aspire.config.json` with the RabbitMQ hosting integration package:
```json title="aspire.config.json" ins={3}
{
"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](#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:
```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
var rabbitmq = builder.AddRabbitMQ("messaging");
var exampleProject = builder.AddProject("apiservice")
.WithReference(rabbitmq);
// After adding all resources, run the app...
```
```typescript title="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.
1. The RabbitMQ server resource includes default credentials with a `username` of `"guest"` and a randomly generated `password` using the `CreateDefaultPasswordParameter` method.
1. 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](../rabbitmq-connect/).
## Add RabbitMQ server resource with data volume
Add a data volume to the RabbitMQ server resource as shown in the following examples:
```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
var rabbitmq = builder.AddRabbitMQ("messaging")
.WithDataVolume(isReadOnly: false);
var exampleProject = builder.AddProject("apiservice")
.WithReference(rabbitmq);
// After adding all resources, run the app...
```
```typescript title="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](#add-rabbitmq-server-resource-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/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:
```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
var rabbitmq = builder.AddRabbitMQ("messaging")
.WithDataBindMount(
source: "/RabbitMQ/Data",
isReadOnly: false);
var exampleProject = builder.AddProject("apiservice")
.WithReference(rabbitmq);
// After adding all resources, run the app...
```
```typescript title="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](https://docs.docker.com/engine/storage/bind-mounts/) have limited functionality compared to [volumes](https://docs.docker.com/engine/storage/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](https://docs.docker.com/engine/storage/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:
```csharp title="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("apiservice")
.WithReference(rabbitmq);
// After adding all resources, run the app...
```
```typescript title="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](https://www.rabbitmq.com/docs/management) as a sub-resource, call `WithManagementPlugin` (or `withManagementPlugin`). You'll need the credentials you configured to log in to the management UI:
```csharp title="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("apiservice")
.WithReference(rabbitmq);
// After adding all resources, run the app...
```
```typescript title="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`](https://hub.docker.com/_/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:
```csharp title="C# — AppHost.cs"
var rabbitmq = builder.AddRabbitMQ("messaging")
.WithManagementPlugin(port: 15672);
```
```typescript title="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:
```csharp title="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 title="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`:
```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
var rabbitmq = builder.AddConnectionString("messaging");
var exampleProject = builder.AddProject("apiservice")
.WithReference(rabbitmq);
// After adding all resources, run the app...
```
```typescript title="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-connect/).
## 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](https://github.com/rabbitmq/rabbitmq-server/releases/tag/v4.3.0).
**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](https://www.nuget.org/packages/AspNetCore.HealthChecks.Rabbitmq) NuGet package.