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.ts — 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.3.0"
  }
}

Совет

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.ts

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

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.

Заметка

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.ts

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

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.ts

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

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...

Заметка

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.ts

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

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.ts

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

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.ts

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.ts

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

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

In C#, call AsExisting instead of AddRabbitMQ to reference an externally managed RabbitMQ instance:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
    .AsExisting(connectionStringParameter: builder.AddParameter("messaging-cs", secret: true));

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

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

TypeScript

The TypeScript AppHost doesn’t currently expose an asExisting(...) API for RabbitMQ. To connect to an existing RabbitMQ instance from a TypeScript AppHost, use builder.addConnectionString(...) with a parameter and reference that connection string from your consuming apps instead.

Connection properties

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

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.