# Hosting API (/integrations/aspire/reference/hosting-api)



The `KubeMQ.Aspire.Hosting` package adds a KubeMQ container resource to your Aspire AppHost. This page documents `AddKubeMQ`, its `With*` builder methods, the container resource it provisions, and the three endpoints it maps. For client-side registration see the [Client API](/integrations/aspire/reference/client-api); for settings and connection strings see [Configuration](/integrations/aspire/reference/configuration).

## Packages [#packages]

The integration ships two NuGet packages following the standard Aspire two-package model — one for the AppHost, one for the consuming service.

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

```bash title="AppHost project"
dotnet add package KubeMQ.Aspire.Hosting
```

```bash title="Service project"
dotnet add package KubeMQ.Aspire.Client
```

## AddKubeMQ and builder methods [#addkubemq-and-builder-methods]

The hosting package extends `IDistributedApplicationBuilder` with `AddKubeMQ` and the resource with three `With*` builder methods. All builder methods return `IResourceBuilder<KubeMQServerResource>` so they chain fluently.

| Method                       | Description                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `AddKubeMQ(name, grpcPort?)` | Add a KubeMQ container resource. `grpcPort` fixes the host-side gRPC port; omit it to let Aspire auto-assign. |
| `WithLicenseKey(parameter)`  | Set the `KUBEMQ_TOKEN` environment variable from a secret `ParameterResource`.                                |
| `WithDataVolume(name?)`      | Bind a persistent volume to `/store`. Defaults the volume name to `{resourceName}-data`.                      |
| `WithImageTag(tag)`          | Override the Docker image tag (default tag: `2.5.0`).                                                         |

```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();
```

<Callout type="info">
  `WithLicenseKey` takes an `IResourceBuilder<ParameterResource>`, not a raw string. Declare the parameter with `builder.AddParameter("kubemq-key", secret: true)` and supply the value via `dotnet user-secrets` or the `Parameters` configuration section so the key never lands in source.
</Callout>

## Container resource [#container-resource]

`AddKubeMQ` registers a `KubeMQServerResource` (a `ContainerResource` that also implements `IResourceWithConnectionString`) and configures the container as follows.

| Property          | Value                                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Image             | `europe-docker.pkg.dev/kubemq/images/kubemq:2.5.0` (registry `europe-docker.pkg.dev`, image `kubemq/images/kubemq`, tag `2.5.0`) |
| Lifetime          | `ContainerLifetime.Persistent` — the container survives AppHost restarts                                                         |
| Connection string | `host:port` for the gRPC endpoint                                                                                                |

The connection string is expressed from the gRPC endpoint as `{host}:{port}` — there is no scheme prefix. This is the value `WithReference(messaging)` injects into a referencing service and that `AddKubeMQClient("messaging")` reads back.

```csharp title="Connection string expression (KubeMQServerResource.cs)"
public ReferenceExpression ConnectionStringExpression =>
    ReferenceExpression.Create(
        $"{GrpcEndpoint.Property(EndpointProperty.Host)}:{GrpcEndpoint.Property(EndpointProperty.Port)}");
```

## Endpoints [#endpoints]

`AddKubeMQ` maps three endpoints on the container. The gRPC endpoint is the primary client connection; REST and Dashboard are exposed for the HTTP API and the web UI.

| Name        | Target Port | Protocol |
| ----------- | ----------- | -------- |
| `grpc`      | 50000       | TCP      |
| `rest`      | 9090        | HTTP     |
| `dashboard` | 8080        | HTTP     |

Only the gRPC endpoint feeds the connection string. The host-side gRPC port is auto-assigned unless you pass `grpcPort` to `AddKubeMQ` — the in-container target port is always `50000`.

## Related [#related]

<Cards>
  <Card title="Client API" href="/integrations/aspire/reference/client-api" description="AddKubeMQClient, AddKeyedKubeMQClient, health checks, and OpenTelemetry registration." />

  <Card title="Configuration" href="/integrations/aspire/reference/configuration" description="KubeMQClientSettings, the connection-string format, and version requirements." />

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