# Client API (/integrations/aspire/reference/client-api)



The `KubeMQ.Aspire.Client` package extends `IHostApplicationBuilder` with two registration methods and wires health checks and OpenTelemetry into the host automatically. This page documents the registration API, the health-check naming and status mapping, and the OpenTelemetry sources. For the settings table and connection-string rules see [Configuration](/integrations/aspire/reference/configuration); for the provisioning side see the [Hosting API](/integrations/aspire/reference/hosting-api).

## Registration methods [#registration-methods]

Use `AddKubeMQClient` for a single broker and `AddKeyedKubeMQClient` once per broker when a service talks to more than one.

| Method                                                                   | Description                                                                                                                                    |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `AddKubeMQClient(connectionName, configureSettings?, configureOptions?)` | Register `IKubeMQClient` as a singleton via SDK DI. `connectionName` matches the AppHost resource name.                                        |
| `AddKeyedKubeMQClient(name, configureSettings?, configureOptions?)`      | Register a keyed `IKubeMQClient` singleton, resolved with `[FromKeyedServices(name)]`. `name` is both the service key and the connection name. |

Both methods accept two optional delegates: `configureSettings` mutates the bound `KubeMQClientSettings`, and `configureOptions` mutates the underlying SDK `KubeMQClientOptions` after settings are applied.

<Callout type="warn">
  `AddKubeMQClient` may be called only once per host — a second call throws `InvalidOperationException`. For multiple KubeMQ connections, use `AddKeyedKubeMQClient` with distinct keys.
</Callout>

```csharp title="Single client"
builder.AddKubeMQClient("messaging");
```

```csharp title="Keyed clients (multiple brokers)"
builder.AddKeyedKubeMQClient("orders");
builder.AddKeyedKubeMQClient("notifications");

// Resolve by key
var ordersClient = host.Services.GetRequiredKeyedService<IKubeMQClient>("orders");
var notifClient = host.Services.GetRequiredKeyedService<IKubeMQClient>("notifications");
```

<Callout type="info">
  The keyed path constructs `KubeMQClient` directly rather than going through SDK DI, because the SDK does not support keyed DI registration. Behavior parity with the non-keyed path is verified by unit tests, but future additions to the SDK's `AddKubeMQ` registration (extra hosted services, wrappers) do **not** automatically apply to keyed clients.
</Callout>

## Health checks [#health-checks]

Unless `DisableHealthChecks` is `true`, the integration registers two health checks per client. Names are derived from the connection name as `kubemq-{name}`.

| Health check name     | Tag     | Reports                     |
| --------------------- | ------- | --------------------------- |
| `kubemq-{name}-ready` | `ready` | Broker connection readiness |
| `kubemq-{name}-live`  | `live`  | Process liveness            |

The readiness check maps the SDK connection state to a health status. The liveness check uses no timeout; the readiness check uses `HealthCheckTimeout` (default `00:00:05`).

| Connection State | Health Status              |
| ---------------- | -------------------------- |
| Ready            | Healthy (with server info) |
| Reconnecting     | Degraded                   |
| Connecting       | Unhealthy                  |
| Idle             | Unhealthy                  |
| Closed           | Unhealthy                  |

The `ready` and `live` tags line up with the `MapDefaultEndpoints` convention in the Aspire `ServiceDefaults`, which maps `/health` to checks tagged `ready` and `/alive` to checks tagged `live`. For the readiness ping behavior and how the checks reach HTTP endpoints, see [Health Checks and OpenTelemetry](/integrations/aspire/how-to/health-checks-observability).

## OpenTelemetry [#opentelemetry]

Unless disabled, the integration registers the SDK's built-in instrumentation on the host's OpenTelemetry pipeline. Both the tracing source and the meter use the name `KubeMQ.Sdk`.

| Signal  | Registration              | Disable with     |
| ------- | ------------------------- | ---------------- |
| Tracing | `AddSource("KubeMQ.Sdk")` | `DisableTracing` |
| Metrics | `AddMeter("KubeMQ.Sdk")`  | `DisableMetrics` |

With both enabled, KubeMQ traces and metrics flow into the same OpenTelemetry pipeline the Aspire dashboard reads, alongside the ASP.NET Core, HTTP client, and runtime instrumentation registered by `AddServiceDefaults`.

## Related [#related]

<Cards>
  <Card title="Hosting API" href="/integrations/aspire/reference/hosting-api" description="AddKubeMQ, builder methods, the container resource, and endpoints." />

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

  <Card title="Health Checks and OpenTelemetry" href="/integrations/aspire/how-to/health-checks-observability" description="Readiness/liveness internals and mapping checks to /health and /alive." />
</Cards>