Skip to content

Commit 6bb1357

Browse files
ramonsmitsramonsmits
committed
📝 Update IBMMQ docs for alpha.6 breaking changes
- Snippets: migrate from callback constructor to object initializer API - Remove MaxMessageLength (removed from transport) - Add circuit breaker section to connection-settings - Document --assembly option for polymorphic subscribe/unsubscribe - Add hierarchy unsubscribe example with warning about unintended removals - Update large message bodies description to reference MAXMSGL
1 parent b04f97f commit 6bb1357

5 files changed

Lines changed: 122 additions & 90 deletions

File tree

‎Snippets/IBMMQ/IBMMQ_1/IBMMQ_1.csproj‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
</PropertyGroup>
66

77
<ItemGroup>
8-
<PackageReference Include="NServiceBus.Transport.IBMMQ" Version="1.0.0-alpha.1" />
8+
<PackageReference Include="NServiceBus.Transport.IBMMQ" Version="1.0.0-alpha.6" />
99
</ItemGroup>
1010

1111
</Project>

‎Snippets/IBMMQ/IBMMQ_1/Usage.cs‎

Lines changed: 64 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@ public void BasicConfig()
1010

1111
var endpointConfiguration = new EndpointConfiguration("MyEndpoint");
1212

13-
var transport = new IBMMQTransport(options =>
13+
var transport = new IBMMQTransport
1414
{
15-
options.Host = "mq-server.example.com";
16-
options.Port = 1414;
17-
options.Channel = "DEV.APP.SVRCONN";
18-
options.QueueManagerName = "QM1";
19-
options.User = "app";
20-
options.Password = "passw0rd";
21-
});
15+
Host = "mq-server.example.com",
16+
Port = 1414,
17+
Channel = "DEV.APP.SVRCONN",
18+
QueueManagerName = "QM1",
19+
User = "app",
20+
Password = "passw0rd"
21+
};
2222

2323
endpointConfiguration.UseTransport(transport);
2424

@@ -29,13 +29,13 @@ public void BasicConnection()
2929
{
3030
#region ibmmq-basic-connection
3131

32-
var transport = new IBMMQTransport(options =>
32+
var transport = new IBMMQTransport
3333
{
34-
options.Host = "mq-server.example.com";
35-
options.Port = 1414;
36-
options.Channel = "DEV.APP.SVRCONN";
37-
options.QueueManagerName = "QM1";
38-
});
34+
Host = "mq-server.example.com",
35+
Port = 1414,
36+
Channel = "DEV.APP.SVRCONN",
37+
QueueManagerName = "QM1"
38+
};
3939

4040
#endregion
4141
}
@@ -44,13 +44,13 @@ public void Authentication()
4444
{
4545
#region ibmmq-authentication
4646

47-
var transport = new IBMMQTransport(options =>
47+
var transport = new IBMMQTransport
4848
{
49-
options.Host = "mq-server.example.com";
50-
options.QueueManagerName = "QM1";
51-
options.User = "app";
52-
options.Password = "passw0rd";
53-
});
49+
Host = "mq-server.example.com",
50+
QueueManagerName = "QM1",
51+
User = "app",
52+
Password = "passw0rd"
53+
};
5454

5555
#endregion
5656
}
@@ -59,11 +59,11 @@ public void ApplicationName()
5959
{
6060
#region ibmmq-application-name
6161

62-
var transport = new IBMMQTransport(options =>
62+
var transport = new IBMMQTransport
6363
{
6464
// ... connection settings ...
65-
options.ApplicationName = "OrderService";
66-
});
65+
ApplicationName = "OrderService"
66+
};
6767

6868
#endregion
6969
}
@@ -72,13 +72,12 @@ public void HighAvailability()
7272
{
7373
#region ibmmq-high-availability
7474

75-
var transport = new IBMMQTransport(options =>
75+
var transport = new IBMMQTransport
7676
{
77-
options.QueueManagerName = "QM1";
78-
options.Channel = "APP.SVRCONN";
79-
options.Connections.Add("mqhost1(1414)");
80-
options.Connections.Add("mqhost2(1414)");
81-
});
77+
QueueManagerName = "QM1",
78+
Channel = "APP.SVRCONN",
79+
Connections = { "mqhost1(1414)", "mqhost2(1414)" }
80+
};
8281

8382
#endregion
8483
}
@@ -87,13 +86,13 @@ public void SslTls()
8786
{
8887
#region ibmmq-ssl-tls
8988

90-
var transport = new IBMMQTransport(options =>
89+
var transport = new IBMMQTransport
9190
{
92-
options.Host = "mq-server.example.com";
93-
options.QueueManagerName = "QM1";
94-
options.SslKeyRepository = "*SYSTEM";
95-
options.CipherSpec = "TLS_RSA_WITH_AES_256_CBC_SHA256";
96-
});
91+
Host = "mq-server.example.com",
92+
QueueManagerName = "QM1",
93+
SslKeyRepository = "*SYSTEM",
94+
CipherSpec = "TLS_RSA_WITH_AES_256_CBC_SHA256"
95+
};
9796

9897
#endregion
9998
}
@@ -102,13 +101,13 @@ public void SslPeerName()
102101
{
103102
#region ibmmq-ssl-peer-name
104103

105-
var transport = new IBMMQTransport(options =>
104+
var transport = new IBMMQTransport
106105
{
107106
// ... connection settings ...
108-
options.SslKeyRepository = "*SYSTEM";
109-
options.CipherSpec = "TLS_RSA_WITH_AES_256_CBC_SHA256";
110-
options.SslPeerName = "CN=MQSERVER01,O=MyCompany,C=US";
111-
});
107+
SslKeyRepository = "*SYSTEM",
108+
CipherSpec = "TLS_RSA_WITH_AES_256_CBC_SHA256",
109+
SslPeerName = "CN=MQSERVER01,O=MyCompany,C=US"
110+
};
112111

113112
#endregion
114113
}
@@ -117,11 +116,11 @@ public void CustomTopicPrefix()
117116
{
118117
#region ibmmq-custom-topic-prefix
119118

120-
var transport = new IBMMQTransport(options =>
119+
var transport = new IBMMQTransport
121120
{
122121
// ... connection settings ...
123-
options.TopicNaming = new TopicNaming("PROD");
124-
});
122+
TopicNaming = new TopicNaming("PROD")
123+
};
125124

126125
#endregion
127126
}
@@ -130,11 +129,11 @@ public void CustomTopicNamingUsage()
130129
{
131130
#region ibmmq-custom-topic-naming-usage
132131

133-
var transport = new IBMMQTransport(options =>
132+
var transport = new IBMMQTransport
134133
{
135134
// ... connection settings ...
136-
options.TopicNaming = new ShortTopicNaming();
137-
});
135+
TopicNaming = new ShortTopicNaming()
136+
};
138137

139138
#endregion
140139
}
@@ -143,15 +142,15 @@ public void ResourceSanitization()
143142
{
144143
#region ibmmq-resource-sanitization
145144

146-
var transport = new IBMMQTransport(options =>
145+
var transport = new IBMMQTransport
147146
{
148147
// ... connection settings ...
149-
options.ResourceNameSanitizer = name =>
148+
ResourceNameSanitizer = name =>
150149
{
151150
var sanitized = name.Replace("-", ".").Replace("/", ".");
152151
return sanitized.Length > 48 ? sanitized[..48] : sanitized;
153-
};
154-
});
152+
}
153+
};
155154

156155
#endregion
157156
}
@@ -160,24 +159,11 @@ public void PollingInterval()
160159
{
161160
#region ibmmq-polling-interval
162161

163-
var transport = new IBMMQTransport(options =>
162+
var transport = new IBMMQTransport
164163
{
165164
// ... connection settings ...
166-
options.MessageWaitInterval = TimeSpan.FromMilliseconds(2000);
167-
});
168-
169-
#endregion
170-
}
171-
172-
public void MaxMessageSize()
173-
{
174-
#region ibmmq-max-message-size
175-
176-
var transport = new IBMMQTransport(options =>
177-
{
178-
// ... connection settings ...
179-
options.MaxMessageLength = 10 * 1024 * 1024; // 10 MB
180-
});
165+
MessageWaitInterval = TimeSpan.FromMilliseconds(2000)
166+
};
181167

182168
#endregion
183169
}
@@ -186,11 +172,11 @@ public void CharacterSet()
186172
{
187173
#region ibmmq-character-set
188174

189-
var transport = new IBMMQTransport(options =>
175+
var transport = new IBMMQTransport
190176
{
191177
// ... connection settings ...
192-
options.CharacterSet = 1208; // UTF-8 (default)
193-
});
178+
CharacterSet = 1208 // UTF-8 (default)
179+
};
194180

195181
#endregion
196182
}
@@ -199,11 +185,11 @@ public void SendsAtomicWithReceive()
199185
{
200186
#region ibmmq-sends-atomic-with-receive
201187

202-
var transport = new IBMMQTransport(options =>
188+
var transport = new IBMMQTransport
203189
{
204190
// ... connection settings ...
205-
});
206-
transport.TransportTransactionMode = TransportTransactionMode.SendsAtomicWithReceive;
191+
TransportTransactionMode = TransportTransactionMode.SendsAtomicWithReceive
192+
};
207193

208194
#endregion
209195
}
@@ -212,11 +198,11 @@ public void ReceiveOnly()
212198
{
213199
#region ibmmq-receive-only
214200

215-
var transport = new IBMMQTransport(options =>
201+
var transport = new IBMMQTransport
216202
{
217203
// ... connection settings ...
218-
});
219-
transport.TransportTransactionMode = TransportTransactionMode.ReceiveOnly;
204+
TransportTransactionMode = TransportTransactionMode.ReceiveOnly
205+
};
220206

221207
#endregion
222208
}
@@ -225,11 +211,11 @@ public void TransactionsNone()
225211
{
226212
#region ibmmq-transactions-none
227213

228-
var transport = new IBMMQTransport(options =>
214+
var transport = new IBMMQTransport
229215
{
230216
// ... connection settings ...
231-
});
232-
transport.TransportTransactionMode = TransportTransactionMode.None;
217+
TransportTransactionMode = TransportTransactionMode.None
218+
};
233219

234220
#endregion
235221
}

‎transports/ibmmq/connection-settings.md‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,14 @@ snippet: ibmmq-resource-sanitization
9696
> [!WARNING]
9797
> 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.
9898
99+
## Circuit breaker
100+
101+
If the transport cannot communicate with the queue manager for a sustained period, it triggers a critical error. The default timeout is 2 minutes:
102+
103+
|Setting|Default|
104+
|:---|---|
105+
|TimeToWaitBeforeTriggeringCircuitBreaker|2 minutes|
106+
99107
## Message processing settings
100108

101109
### Polling interval
@@ -108,16 +116,6 @@ snippet: ibmmq-polling-interval
108116
|:---|---|---|
109117
|MessageWaitInterval|5000 ms|100–30,000 ms|
110118

111-
### Maximum message size
112-
113-
Should match or be less than the queue manager's `MAXMSGL` setting:
114-
115-
snippet: ibmmq-max-message-size
116-
117-
|Setting|Default|Range|
118-
|:---|---|---|
119-
|MaxMessageLength|4 MB|1 KB – 100 MB|
120-
121119
### Character set
122120

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

‎transports/ibmmq/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ The transport requires IBM MQ 9.0 or later.
2020
|Transactions |None, ReceiveOnly, SendsAtomicWithReceive
2121
|Pub/Sub |Native
2222
|Timeouts |Not natively supported
23-
|Large message bodies |Up to 100 MB (configurable)
23+
|Large message bodies |Determined by queue manager `MAXMSGL` setting
2424
|Scale-out |Competing consumer
2525
|Scripted Deployment |Supported via [CLI tool](operations-scripting.md)
2626
|Installers |Optional

‎transports/ibmmq/operations-scripting.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,21 @@ This command:
8585
1. Creates a topic object named `PROD.MYCOMPANY.EVENTS.ORDERPLACED` (if it does not exist).
8686
2. Creates a durable subscription linking the topic to the `OrderService` input queue.
8787

88+
#### Polymorphic subscriptions
89+
90+
To subscribe to a base class or interface and all its concrete implementations, provide the `--assembly` option with the path to the assembly containing the event types:
91+
92+
```bash
93+
ibmmq-transport endpoint subscribe OrderService \
94+
"MyCompany.Events.IOrderEvent" \
95+
--topic-prefix PROD \
96+
--assembly /path/to/MyCompany.Events.dll
97+
```
98+
99+
The CLI loads the assembly, discovers all types that derive from or implement the specified event type, and creates a subscription for each.
100+
101+
Without `--assembly`, only a single subscription for the exact type name is created.
102+
88103
### Unsubscribe an endpoint from an event
89104

90105
Removes the durable subscription for an event type:
@@ -94,6 +109,39 @@ ibmmq-transport endpoint unsubscribe <name> <event-type> \
94109
--topic-prefix DEV
95110
```
96111

112+
The `--assembly` option can also be used with `unsubscribe` to remove subscriptions for all derived types at once. Given the following event hierarchy:
113+
114+
```csharp
115+
public interface IOrderEvent { }
116+
public class OrderPlaced : IOrderEvent { }
117+
public class OrderBilled : IOrderEvent { }
118+
public class OrderCancelled : IOrderEvent { }
119+
public class PriorityOrderPlaced : OrderPlaced { }
120+
```
121+
122+
Unsubscribing from `OrderPlaced` with the `--assembly` option:
123+
124+
```bash
125+
ibmmq-transport endpoint unsubscribe OrderService \
126+
"MyCompany.Events.OrderPlaced" \
127+
--topic-prefix PROD \
128+
--assembly /path/to/MyCompany.Events.dll
129+
```
130+
131+
This removes subscriptions for `OrderPlaced` **and** `PriorityOrderPlaced` (its derived type), but leaves subscriptions for `OrderBilled`, `OrderCancelled`, and `IOrderEvent` intact.
132+
133+
> [!WARNING]
134+
> Using `--assembly` to unsubscribe from a type in the middle of a hierarchy removes subscriptions for that type and **all types below it**. This can silently stop event delivery if other parts of the system still expect those events to arrive. Prefer unsubscribing from each concrete event type individually:
135+
>
136+
> ```bash
137+
> ibmmq-transport endpoint unsubscribe OrderService \
138+
> "MyCompany.Events.OrderPlaced" --topic-prefix PROD
139+
> ibmmq-transport endpoint unsubscribe OrderService \
140+
> "MyCompany.Events.PriorityOrderPlaced" --topic-prefix PROD
141+
> ```
142+
>
143+
> This makes each removal explicit and avoids accidentally unsubscribing from derived types that are still needed.
144+
97145
### Using environment variables
98146
99147
For repeated use, connection details can be provided via environment variables:

0 commit comments

Comments
 (0)