Basic connection
The transport connects to an IBM MQ queue manager using a host, port, and SVRCONN channel:
var transport = new IBMMQTransport
{
Host = "mq-server.example.com",
Port = 1414,
Channel = "DEV.APP.SVRCONN",
QueueManagerName = "QM1"
};
Defaults
| Setting | Default |
|---|---|
| Host | localhost |
| Port | 1414 |
| Channel | DEV. |
| QueueManagerName | Empty (local default queue manager named QM1) |
Authentication
User credentials can be provided to authenticate with the queue manager:
var transport = new IBMMQTransport
{
Host = "mq-server.example.com",
QueueManagerName = "QM1",
User = "app",
Password = "passw0rd"
};
Application name
The application name appears in IBM MQ monitoring tools and is useful for identifying connections:
var transport = new IBMMQTransport
{
// ... connection settings ...
ApplicationName = "OrderService"
};
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:
var transport = new IBMMQTransport
{
QueueManagerName = "QM1",
Channel = "APP.SVRCONN",
Connections = { "mqhost1(1414)", "mqhost2(1414)" }
};
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.
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.
var transport = new IBMMQTransport
{
Host = "mq-server.example.com",
QueueManagerName = "QM1",
SslKeyRepository = "*SYSTEM",
CipherSpec = "TLS_RSA_WITH_AES_256_CBC_SHA256"
};
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., / |
Peer name verification
Verify the queue manager's certificate distinguished name for additional security:
var transport = new IBMMQTransport
{
// ... connection settings ...
SslKeyRepository = "*SYSTEM",
CipherSpec = "TLS_RSA_WITH_AES_256_CBC_SHA256",
SslPeerName = "CN=MQSERVER01,O=MyCompany,C=US"
};
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:
var transport = new IBMMQTransport
{
// ... connection settings ...
TopicNaming = new TopicNaming("PROD")
};
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:
public sealed class ShortTopicNaming() : TopicNaming("APP")
{
public override string GenerateTopicName(Type eventType)
{
return $"APP.{eventType.Name}".ToUpperInvariant();
}
}
var transport = new IBMMQTransport
{
// ... connection settings ...
TopicNaming = new ShortTopicNaming()
};
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:
var transport = new IBMMQTransport
{
// ... connection settings ...
ResourceNameSanitizer = name =>
{
var sanitized = name.Replace("-", ".").Replace("/", ".");
return sanitized.Length > 48 ? sanitized[..48] : sanitized;
}
};
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. The default timeout is 2 minutes:
var transport = new IBMMQTransport
{
// ... connection settings ...
TimeToWaitBeforeTriggeringCircuitBreaker = TimeSpan.FromMinutes(5)
};
| Setting | Default |
|---|---|
| TimeToWaitBeforeTriggeringCircuitBreaker | 2 minutes |
Message processing settings
Polling interval
The wait interval controls how long each poll waits for a message before returning:
var transport = new IBMMQTransport
{
// ... connection settings ...
MessageWaitInterval = TimeSpan.FromMilliseconds(2000)
};
| 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.
var transport = new IBMMQTransport
{
// ... connection settings ...
CharacterSet = 1208 // UTF-8 (default)
};