# Configuration (/integrations/aspire/reference/configuration)



This page is the complete configuration surface for the `KubeMQ.Aspire.Client` package: the configuration sections each registration method binds, the full `KubeMQClientSettings` table, the connection-string parsing rules, and the supported runtime and dependency versions. For the registration methods themselves see the [Client API](/integrations/aspire/reference/client-api); for a task-oriented walkthrough see the [Client Configuration and TLS](/integrations/aspire/how-to/configuration-and-tls) guide.

## Configuration sections [#configuration-sections]

Client settings are bound from configuration before the `configureSettings` delegate runs. The configuration section depends on which registration method you call.

| Registration                     | Configuration section         |
| -------------------------------- | ----------------------------- |
| `AddKubeMQClient("messaging")`   | `Aspire:KubeMQ:Client`        |
| `AddKeyedKubeMQClient("orders")` | `Aspire:KubeMQ:Client:orders` |

The top-level `Aspire:KubeMQ:Client` section configures the default client. Named subsections under it — `Aspire:KubeMQ:Client:{name}` — configure each keyed client, where `{name}` matches the service key.

<Tabs items="[&#x22;Default client&#x22;, &#x22;Keyed clients&#x22;]">
  <Tab value="Default client">
    ```json title="appsettings.json"
    {
      "Aspire": {
        "KubeMQ": {
          "Client": {
            "DisableHealthChecks": false,
            "DisableTracing": false,
            "DisableMetrics": false,
            "HealthCheckTimeout": "00:00:05",
            "AuthToken": null,
            "ClientId": null
          }
        }
      }
    }
    ```
  </Tab>

  <Tab value="Keyed clients">
    ```json title="appsettings.json"
    {
      "Aspire": {
        "KubeMQ": {
          "Client": {
            "orders": {
              "ClientId": "orders-service",
              "GrpcChannelCount": 8
            },
            "notifications": {
              "DisableTracing": true
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Settings can also be set in code via the `configureSettings` delegate, which is applied after binding and overrides configured values:

```csharp title="Service/Program.cs"
builder.AddKubeMQClient("messaging", settings =>
{
    settings.DisableHealthChecks = true;
    settings.AuthToken = "my-token";
});
```

## KubeMQClientSettings [#kubemqclientsettings]

Every property on `KubeMQClientSettings`. Properties whose default is "SDK default" are nullable — leaving them `null` passes through to the underlying `KubeMQ.SDK.CSharp` default shown in parentheses.

<TypeTable
  type="{
  ConnectionString: {
    type: &#x22;string?&#x22;,
    default: &#x22;null&#x22;,
    description: &#x22;gRPC connection string in host:port format. When null, the address is resolved from the Aspire connection string named after the connection.&#x22;,
  },
  DisableHealthChecks: {
    type: &#x22;bool&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Disable readiness and liveness health-check registration.&#x22;,
  },
  DisableTracing: {
    type: &#x22;bool&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Disable OpenTelemetry tracing (the KubeMQ.Sdk activity source).&#x22;,
  },
  DisableMetrics: {
    type: &#x22;bool&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Disable OpenTelemetry metrics (the KubeMQ.Sdk meter).&#x22;,
  },
  HealthCheckTimeout: {
    type: &#x22;TimeSpan&#x22;,
    default: &#x22;00:00:05&#x22;,
    description: &#x22;Timeout applied to the readiness health check. Must be positive when health checks are enabled.&#x22;,
  },
  AuthToken: {
    type: &#x22;string?&#x22;,
    default: &#x22;null&#x22;,
    description: &#x22;JWT authentication token, passed through to the SDK.&#x22;,
  },
  ClientId: {
    type: &#x22;string?&#x22;,
    default: &#x22;null&#x22;,
    description: &#x22;Client identifier, passed through to the SDK.&#x22;,
  },
  DefaultTimeout: {
    type: &#x22;TimeSpan?&#x22;,
    default: &#x22;null (SDK 5s)&#x22;,
    description: &#x22;SDK operation timeout. Null uses the SDK default of 5 seconds.&#x22;,
  },
  ConnectionTimeout: {
    type: &#x22;TimeSpan?&#x22;,
    default: &#x22;null (SDK 10s)&#x22;,
    description: &#x22;SDK connection timeout. Null uses the SDK default of 10 seconds.&#x22;,
  },
  UseTls: {
    type: &#x22;bool&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Enable TLS for the gRPC connection. Default is plain HTTP for local dev containers.&#x22;,
  },
  TlsCertFile: {
    type: &#x22;string?&#x22;,
    default: &#x22;null&#x22;,
    description: &#x22;Path to the client TLS certificate file (PEM). Used only when UseTls is true.&#x22;,
  },
  TlsKeyFile: {
    type: &#x22;string?&#x22;,
    default: &#x22;null&#x22;,
    description: &#x22;Path to the client TLS private key file (PEM). Used only when UseTls is true.&#x22;,
  },
  TlsCaFile: {
    type: &#x22;string?&#x22;,
    default: &#x22;null&#x22;,
    description: &#x22;Path to the CA certificate file (PEM). Used only when UseTls is true.&#x22;,
  },
  TlsServerNameOverride: {
    type: &#x22;string?&#x22;,
    default: &#x22;null&#x22;,
    description: &#x22;Server name override for TLS certificate verification.&#x22;,
  },
  TlsInsecureSkipVerify: {
    type: &#x22;bool&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Skip TLS certificate verification. Development only.&#x22;,
  },
  GrpcChannelCount: {
    type: &#x22;int?&#x22;,
    default: &#x22;null (SDK 5)&#x22;,
    description: &#x22;Number of gRPC channels to pool, 1–16. Null uses the SDK default of 5.&#x22;,
  },
  MaxSendSize: {
    type: &#x22;int?&#x22;,
    default: &#x22;null (SDK 100 MB)&#x22;,
    description: &#x22;Max gRPC send message size in bytes. Null uses the SDK default of 104857600 (100 MB).&#x22;,
  },
  MaxReceiveSize: {
    type: &#x22;int?&#x22;,
    default: &#x22;null (SDK 100 MB)&#x22;,
    description: &#x22;Max gRPC receive message size in bytes. Null uses the SDK default of 104857600 (100 MB).&#x22;,
  },
  WaitForReady: {
    type: &#x22;bool?&#x22;,
    default: &#x22;null (SDK true)&#x22;,
    description: &#x22;Block operations until the connection is ready. Null uses the SDK default of true.&#x22;,
  },
  KeepalivePingInterval: {
    type: &#x22;TimeSpan?&#x22;,
    default: &#x22;null (SDK 10s)&#x22;,
    description: &#x22;gRPC keepalive ping interval. Null uses the SDK default of 10 seconds.&#x22;,
  },
  KeepalivePingTimeout: {
    type: &#x22;TimeSpan?&#x22;,
    default: &#x22;null (SDK 5s)&#x22;,
    description: &#x22;gRPC keepalive ping ACK timeout. Null uses the SDK default of 5 seconds.&#x22;,
  },
  ReconnectEnabled: {
    type: &#x22;bool?&#x22;,
    default: &#x22;null (SDK true)&#x22;,
    description: &#x22;Enable auto-reconnection. Null uses the SDK default of true.&#x22;,
  },
  ReconnectMaxAttempts: {
    type: &#x22;int?&#x22;,
    default: &#x22;null (SDK 0)&#x22;,
    description: &#x22;Max reconnect attempts, 0 = unlimited. Null uses the SDK default of 0.&#x22;,
  },
  ReconnectTimeout: {
    type: &#x22;TimeSpan?&#x22;,
    default: &#x22;null (SDK 60s)&#x22;,
    description: &#x22;Timeout for the reconnect wait-for-ready. Null uses the SDK default of 60 seconds.&#x22;,
  },
}"
/>

`GrpcChannelCount` is constrained to the range 1–16 by the configuration schema. The `Tls*` properties take effect only when `UseTls` is `true`; otherwise they are ignored. For a guided tour of TLS, gRPC tuning, keepalive, and reconnect, see [Client Configuration and TLS](/integrations/aspire/how-to/configuration-and-tls).

## Connection string format [#connection-string-format]

The integration parses the connection string into a `host` and `port` before constructing the client. The parser enforces strict rules — violations throw a `KubeMQConfigurationException`.

| Rule                   | Detail                                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| Plain `host:port`      | The standard form, e.g. `localhost:50000`.                                                           |
| No scheme prefix       | A string containing `://` is rejected — supply `host:port`, not `grpc://host:port`.                  |
| IPv6 requires brackets | An IPv6 address must use `[host]:port`, e.g. `[::1]:50000`. An unbracketed IPv6 address is rejected. |
| Port range             | The port must parse as an integer between `1` and `65535`.                                           |
| Non-empty host         | The host component must not be empty after parsing.                                                  |

```text title="Valid"
localhost:50000
messaging:50000
[::1]:50000
```

```text title="Rejected"
grpc://localhost:50000   # scheme prefix
::1:50000                # IPv6 without brackets
localhost:70000          # port out of range
```

<Callout type="info">
  In an Aspire app you normally never write this string by hand — `WithReference(messaging)` injects it as the connection string and `AddKubeMQClient("messaging")` resolves it. Setting `ConnectionString` explicitly in `KubeMQClientSettings` overrides the injected value and takes precedence.
</Callout>

## Requirements [#requirements]

| Requirement        | Version                                    |
| ------------------ | ------------------------------------------ |
| .NET SDK           | 8.0 or 9.0                                 |
| .NET Aspire        | 9.0+                                       |
| Docker             | Running (for local container provisioning) |
| KubeMQ license key | Set via `WithLicenseKey()`                 |

The packages build on these dependency versions:

| Dependency          | Version |
| ------------------- | ------- |
| `Aspire.Hosting`    | 9.0.0   |
| `KubeMQ.SDK.CSharp` | 3.0.1   |

The KubeMQ .NET Aspire integration is licensed under **Apache 2.0**.

## Related [#related]

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

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

  <Card title="Client Configuration and TLS" href="/integrations/aspire/how-to/configuration-and-tls" description="appsettings.json conventions, TLS/mTLS, gRPC tuning, keepalive, and reconnect." />
</Cards>