# Connection Settings


## Basic connection

The transport connects to an IBM MQ queue manager using a host, port, and SVRCONN channel:

<!-- snippet: ibmmq-basic-connection -->

```cs
var transport = new IBMMQTransport
{
    Host = "mq-server.example.com",
    Port = 1414,
    Channel = "DEV.APP.SVRCONN",
    QueueManagerName = "QM1"
};
```

<!-- endsnippet -->

### Defaults

|Setting|Default|
|:---|---|
|Host|`localhost`|
|Port|`1414`|
|Channel|`DEV.ADMIN.SVRCONN`|
|QueueManagerName|Empty (local default queue manager named QM1)|

## Authentication

User credentials can be provided to authenticate with the queue manager:

<!-- snippet: ibmmq-authentication -->

```cs
var transport = new IBMMQTransport
{
    Host = "mq-server.example.com",
    QueueManagerName = "QM1",
    User = "app",
    Password = "passw0rd"
};
```

<!-- endsnippet -->

## Application name

The application name appears in IBM MQ monitoring tools and is useful for identifying connections:

<!-- snippet: ibmmq-application-name -->

```cs
var transport = new IBMMQTransport
{
    // ... connection settings ...
    ApplicationName = "OrderService"
};
```

<!-- endsnippet -->

If not specified, the application name defaults to the entry assembly name.

## High availability

For high availability scenarios with multi-instance queue managers, provide a connection name list instead of a single host and port:

<!-- snippet: ibmmq-high-availability -->

```cs
var transport = new IBMMQTransport
{
    QueueManagerName = "QM1",
    Channel = "APP.SVRCONN",
    Connections = { "mqhost1(1414)", "mqhost2(1414)" }
};
```

<!-- endsnippet -->

When `Connections` is specified, the `Host` and `Port` properties are ignored. The client will attempt each connection in order, connecting to the first available queue manager.

> [!NOTE]
> All entries in the connection name list must point to instances of the same queue manager (by name). This provides failover to a standby instance, not load balancing.

## SSL/TLS

To enable encrypted communication, configure the SSL key repository and cipher specification. The cipher must match the `SSLCIPH` attribute on the SVRCONN channel.

<!-- snippet: ibmmq-ssl-tls -->

```cs
var transport = new IBMMQTransport
{
    Host = "mq-server.example.com",
    QueueManagerName = "QM1",
    SslKeyRepository = "*SYSTEM",
    CipherSpec = "TLS_RSA_WITH_AES_256_CBC_SHA256"
};
```

<!-- endsnippet -->

### Key repository options

|Value|Description|
|:---|---|
|`*SYSTEM`|Windows system certificate store|
|`*USER`|Windows user certificate store|
|File path|Path to a key database file (without extension), e.g., `/var/mqm/ssl/key`|

### Peer name verification

Verify the queue manager's certificate distinguished name for additional security:

<!-- snippet: ibmmq-ssl-peer-name -->

```cs
var transport = new IBMMQTransport
{
    // ... connection settings ...
    SslKeyRepository = "*SYSTEM",
    CipherSpec = "TLS_RSA_WITH_AES_256_CBC_SHA256",
    SslPeerName = "CN=MQSERVER01,O=MyCompany,C=US"
};
```

<!-- endsnippet -->

> [!NOTE]
> Both `SslKeyRepository` and `CipherSpec` must be specified together. Setting one without the other will cause a configuration validation error.

## Topic naming

Topics are named using a configurable `TopicNaming` strategy. The default uses a prefix of `DEV` and the fully qualified type name.

### Custom topic prefix

To change the prefix:

<!-- snippet: ibmmq-custom-topic-prefix -->

```cs
var transport = new IBMMQTransport
{
    // ... connection settings ...
    TopicNaming = new TopicNaming("PROD")
};
```

<!-- endsnippet -->

### Custom topic naming strategy

IBM MQ topic names are limited to 48 characters. If event type names are long, subclass `TopicNaming` to implement a shortening strategy:

<!-- snippet: ibmmq-custom-topic-naming-class -->

```cs
public sealed class ShortTopicNaming() : TopicNaming("APP")
{
    public override string GenerateTopicName(Type eventType)
    {
        return $"APP.{eventType.Name}".ToUpperInvariant();
    }
}
```

<!-- endsnippet -->

<!-- snippet: ibmmq-custom-topic-naming-usage -->

```cs
var transport = new IBMMQTransport
{
    // ... connection settings ...
    TopicNaming = new ShortTopicNaming()
};
```

<!-- endsnippet -->

## Resource name sanitization

IBM MQ queue and topic names are limited to 48 characters and allow only `A-Z`, `a-z`, `0-9`, `.`, and `_`.
If endpoint names contain invalid characters or are too long, you need to configure a sanitizer:

<!-- snippet: ibmmq-resource-sanitization -->

```cs
var transport = new IBMMQTransport
{
    // ... connection settings ...
    ResourceNameSanitizer = name =>
    {
        var sanitized = name.Replace("-", ".").Replace("/", ".");
        return sanitized.Length > 48 ? sanitized[..48] : sanitized;
    }
};
```

<!-- endsnippet -->

> [!WARNING]
> Ensure the sanitizer produces deterministic and unique names. Two different input names mapping to the same sanitized name will cause messages to be delivered to the wrong endpoint.

## Circuit breaker

If the transport cannot communicate with the queue manager for a sustained period, it triggers a [critical error](/nservicebus/hosting/critical-errors.md). The default timeout is 2 minutes:

<!-- snippet: ibmmq-circuit-breaker -->

```cs
var transport = new IBMMQTransport
{
    // ... connection settings ...
    TimeToWaitBeforeTriggeringCircuitBreaker = TimeSpan.FromMinutes(5)
};
```

<!-- endsnippet -->

|Setting|Default|
|:---|---|
|TimeToWaitBeforeTriggeringCircuitBreaker|2 minutes|

## Message processing settings

### Polling interval

The wait interval controls how long each poll waits for a message before returning:

<!-- snippet: ibmmq-polling-interval -->

```cs
var transport = new IBMMQTransport
{
    // ... connection settings ...
    MessageWaitInterval = TimeSpan.FromMilliseconds(2000)
};
```

<!-- endsnippet -->

|Setting|Default|Range|
|:---|---|---|
|MessageWaitInterval|5000 ms|100–30,000 ms|

### Character set

The Coded Character Set Identifier (CCSID) used for message text encoding. The default is UTF-8 (1208), which is recommended for most scenarios.

<!-- snippet: ibmmq-character-set -->

```cs
var transport = new IBMMQTransport
{
    // ... connection settings ...
    CharacterSet = 1208 // UTF-8 (default)
};
```

<!-- endsnippet -->