# .NET Aspire (/integrations/aspire)



The KubeMQ .NET Aspire integration wires the [KubeMQ](https://kubemq.io) message broker into the [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/) application model. It follows the standard Aspire two-package model: `KubeMQ.Aspire.Hosting` provisions a KubeMQ container in your AppHost, and `KubeMQ.Aspire.Client` configures an `IKubeMQClient` in each consuming service — complete with health checks, OpenTelemetry, and keyed dependency injection. The client is a **native gRPC SDK client** that connects to the broker on port `50000`; there is no connector to enable.

New to the idea? See [what is an integration](/integrations#what-an-integration-is) for how SDK-level integrations differ from server-side [connectors](/connectors).

## Why KubeMQ + .NET Aspire? [#why-kubemq--net-aspire]

* **Container auto-provisioning** — `AddKubeMQ("messaging")` in the AppHost runs a KubeMQ broker container with the gRPC, REST, and Dashboard endpoints already mapped
* **Zero-config connection strings** — `WithReference(messaging)` injects the broker address into each service as an Aspire connection string; `AddKubeMQClient("messaging")` reads it back automatically, so no host or port is hard-coded
* **Built-in health checks** — readiness and liveness checks are registered out of the box with `ready` and `live` tags, surfacing the SDK's connection state to the Aspire dashboard and Kubernetes probes
* **OpenTelemetry on by default** — the SDK's `KubeMQ.Sdk` tracing source and meter are registered automatically, so traces and metrics flow into the Aspire telemetry pipeline with no extra code
* **Keyed DI for multiple brokers** — `AddKeyedKubeMQClient` registers a distinct `IKubeMQClient` per named broker, resolved with `[FromKeyedServices(...)]`

## The two packages [#the-two-packages]

| Package                 | Project | Responsibility                                                            |
| ----------------------- | ------- | ------------------------------------------------------------------------- |
| `KubeMQ.Aspire.Hosting` | AppHost | Provision KubeMQ containers in the Aspire AppHost                         |
| `KubeMQ.Aspire.Client`  | Service | Configure `IKubeMQClient` with health checks, OpenTelemetry, and keyed DI |

## Install [#install]

Add the hosting package to your **AppHost** project:

```bash
dotnet add package KubeMQ.Aspire.Hosting
```

Add the client package to each **service** project that talks to KubeMQ:

```bash
dotnet add package KubeMQ.Aspire.Client
```

## Quick start [#quick-start]

Provision the broker in the AppHost and reference it from a service. The connection string flows from the container resource into the service automatically.

```csharp title="AppHost/Program.cs"
var builder = DistributedApplication.CreateBuilder(args);

var kubemqKey = builder.AddParameter("kubemq-key", secret: true);

var messaging = builder.AddKubeMQ("messaging")
    .WithLicenseKey(kubemqKey)
    .WithDataVolume();

builder.AddProject<Projects.MyWebApi>("webapi")
    .WithReference(messaging)
    .WaitFor(messaging);

builder.Build().Run();
```

```csharp title="MyWebApi/Program.cs"
var builder = WebApplication.CreateBuilder(args);

builder.AddKubeMQClient("messaging");

var app = builder.Build();
app.Run();
```

`AddKubeMQClient` registers `IKubeMQClient` as a singleton and resolves the broker address from the `"messaging"` connection string injected by `WithReference`. For the full walkthrough — parameters, secrets, and verifying the connection — see [Getting Started](/integrations/aspire/tutorials/getting-started).

## Architecture [#architecture]

The AppHost provisions the KubeMQ container and injects its address as a connection string into each referencing service. In the service, `AddKubeMQClient` reads that connection string, constructs an `IKubeMQClient` that speaks gRPC to the broker on port `50000`, and registers the health checks and OpenTelemetry instrumentation as side outputs into the Aspire pipeline.

<Mermaid
  chart="flowchart LR
    subgraph AppHost[&#x22;AppHost — KubeMQ.Aspire.Hosting&#x22;]
        Add[&#x22;AddKubeMQ('messaging')&#x22;]
        Add --> Cont[&#x22;KubeMQ container<br/>europe-docker.pkg.dev/kubemq/images/kubemq:2.5.0&#x22;]
    end
    Add -->|&#x22;connection string<br/>(host:port)&#x22;| Svc
    subgraph Service[&#x22;Service — KubeMQ.Aspire.Client&#x22;]
        Svc[&#x22;AddKubeMQClient('messaging')&#x22;]
        Svc --> Client[&#x22;IKubeMQClient&#x22;]
        Svc -.-> HC[&#x22;Health checks<br/>(ready / live)&#x22;]
        Svc -.-> OTel[&#x22;OpenTelemetry<br/>(KubeMQ.Sdk)&#x22;]
    end
    Client -->|&#x22;gRPC :50000&#x22;| Cont"
/>

*The AppHost provisions the broker container and injects its `host:port` address; the service resolves it by connection name, builds an `IKubeMQClient`, and gets health checks and telemetry for free.*

## What the integration provisions [#what-the-integration-provisions]

The hosting package provisions a real KubeMQ container; the client package layers Aspire conventions on top of the KubeMQ .NET SDK.

| Feature                 | Detail                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------- |
| **Container image**     | `AddKubeMQ` runs `europe-docker.pkg.dev/kubemq/images/kubemq:2.5.0`                     |
| **gRPC endpoint**       | Target port `50000` (TCP) — the primary client connection                               |
| **REST endpoint**       | Target port `9090` (HTTP)                                                               |
| **Dashboard endpoint**  | Target port `8080` (HTTP)                                                               |
| **Persistent lifetime** | The container uses `ContainerLifetime.Persistent`, so it survives AppHost restarts      |
| **Persistent storage**  | `WithDataVolume()` binds a volume to `/store` for durable messages                      |
| **License key**         | `WithLicenseKey()` sets the `KUBEMQ_TOKEN` environment variable from a secret parameter |
| **Image override**      | `WithImageTag()` overrides the default image tag                                        |
| **Health checks**       | Readiness (`ready`) and liveness (`live`) checks reporting the SDK connection state     |
| **OpenTelemetry**       | Tracing source and meter `KubeMQ.Sdk` registered by default                             |
| **Keyed DI**            | `AddKeyedKubeMQClient` for multiple named brokers in one service                        |

## Supported runtime [#supported-runtime]

| Requirement         | Version                                       |
| ------------------- | --------------------------------------------- |
| Language            | C# (.NET)                                     |
| .NET runtime        | .NET 8.0 or .NET 9.0                          |
| .NET Aspire         | 9.0+                                          |
| `KubeMQ.SDK.CSharp` | 3.0.1                                         |
| KubeMQ broker       | gRPC on `:50000` (always on — no enable flag) |

## Messaging patterns [#messaging-patterns]

Once `IKubeMQClient` is injected, it speaks the full KubeMQ messaging surface through the native SDK. The capability pages document the Aspire-specific wiring and link out to the core pattern docs for the send/receive semantics.

<Cards>
  <Card title="Pub/Sub & Events Store" href="/integrations/aspire/how-to/events" description="Fire-and-forget Events and persistent Events Store replay through the injected client." />

  <Card title="Queues" href="/integrations/aspire/how-to/queues" description="Durable point-to-point messaging with competing consumers and ack/nack." />

  <Card title="Commands & Queries" href="/integrations/aspire/how-to/commands-queries" description="Synchronous request-response messaging for command and query patterns." />
</Cards>

## Quick links [#quick-links]

<Cards>
  <Card title="Getting Started" href="/integrations/aspire/tutorials/getting-started" description="Provision a broker, reference it from a service, and send your first message." />

  <Card title="Concepts" href="/integrations/aspire/concepts" description="The two-package model, connection-string injection, keyed DI, and observability." />

  <Card title="Client Configuration & TLS" href="/integrations/aspire/how-to/configuration-and-tls" description="Settings, appsettings.json conventions, health-check tuning, and TLS/mTLS." />

  <Card title="Hosting API Reference" href="/integrations/aspire/reference/hosting-api" description="Hosting and client extension methods, settings, and configuration keys." />
</Cards>

<Callout type="info">
  **Requirements** — .NET 8.0 or .NET 9.0, .NET Aspire 9.0 or later, a KubeMQ license key set via `WithLicenseKey()`, and Docker for local development with Aspire.
</Callout>

New to KubeMQ? Start with the [KubeMQ Getting Started guide](/deploy) for core concepts like Events, Queues, and RPC before wiring up Aspire.