Client API
AddKubeMQClient and AddKeyedKubeMQClient registration methods, plus the health checks and OpenTelemetry sources the client wires by default.
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; for the provisioning side see the Hosting API.
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.
AddKubeMQClient may be called only once per host — a second call throws InvalidOperationException. For multiple KubeMQ connections, use AddKeyedKubeMQClient with distinct keys.
builder.AddKubeMQClient("messaging");builder.AddKeyedKubeMQClient("orders");
builder.AddKeyedKubeMQClient("notifications");
// Resolve by key
var ordersClient = host.Services.GetRequiredKeyedService<IKubeMQClient>("orders");
var notifClient = host.Services.GetRequiredKeyedService<IKubeMQClient>("notifications");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.
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.
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
Was this page helpful?