.NET Client

The IBM MQ .NET client brings messaging to C# services, ASP.NET Core APIs, Windows services, and cross-platform .NET 8 workers that exchange data with mainframe-connected queue managers. Whether you use XMS interfaces familiar to JMS developers or lower-level MQ .NET classes, the runtime loads amqmdnet assemblies that call into the same native client code Java uses—opening TCP to SVRCONN, honoring CCDT from MQCHLLIB, and surfacing reason codes like 2035 when server authority is wrong. Teams new to mainframe integration often assume Windows Active Directory credentials flow automatically to MQ; they do not unless CONNAUTH and channel mapping say so. This tutorial covers XMS connection factories, Hashtable-style property bags for host and channel, NuGet and redistributable installation, TLS on Linux containers, async and dependency-injection patterns in ASP.NET Core, pooling and performance, and operational alignment with Java peers on the same SVRCONN names.

XMS Connection Factory

XMSFactoryFactory.GetInstance(XMSConstants.XMS_DOMINO_MODE_NOT_RELATED) or WMQ-specific factory creation yields IConnectionFactory. Set properties: XMSConst.WMQ_HOST_NAME, WMQ_PORT, WMQ_CHANNEL, WMQ_QUEUE_MANAGER, WMQ_CONNECTION_MODE client. CreateConnection then CreateSession, createQueue, createProducer, send IXMSMessage. Property names are string constants in Hashtable or factory setters depending on API style. Typos in property keys fail at runtime with opaque errors—copy from IBM samples for your exact version.

Sample Connect Pattern

1
2
3
4
5
6
7
8
9
10
11
12
13
// Illustrative XMS .NET — verify against your MQ .NET client version docs
Hashtable props = new Hashtable();
props.Add(XMSConst.WMQ_CONNECTION_MODE, XMSConst.WMQ_CM_CLIENT);
props.Add(XMSConst.WMQ_HOST_NAME, "mq-prod.corp");
props.Add(XMSConst.WMQ_PORT, "1414");
props.Add(XMSConst.WMQ_CHANNEL, "ORDERS.API");
props.Add(XMSConst.WMQ_QUEUE_MANAGER, "QM_PROD");
IConnectionFactory factory = XMSFactoryFactory
  .GetInstance(XMSConstants.XMSDOM)
  .CreateConnectionFactory();
factory.SetProperty(XMSConst.WMQ_CONNECTION_MODE, props[...]);
IConnection conn = factory.CreateConnection();
conn.Start();

After Start, sessions send and receive. Use try/finally or using patterns to close connections on shutdown—IIS app pool recycle without dispose exhausts SVRCONN MAXINST. ASP.NET Core hosted services should implement IHostedService.StopAsync to disconnect cleanly during deploys.

Installation and NuGet

Development machines install IBM MQ client redistributable or reference NuGet packages IBM publishes for supported releases. CI agents need the same native DLLs amqmdnet loads—missing mqm.dll on PATH causes DllNotFoundException before any MQ logic runs. Container images copy client from IBM base image layers. Pin versions in csproj and document upgrade testing against queue manager maintenance windows.

ASP.NET Core Configuration

• Store host, channel, QM in appsettings.json or environment variables.
• Register singleton ConnectionFactory built at startup.
• Use IOptions pattern for per-environment overrides.
• Mount CCDT volume and set MQCHLLIB for ops-owned connection changes.
• Health checks probe MQCONN in readiness endpoint when messaging is critical.

TLS and Windows Versus Linux

Configure SSL cipher and certificate stores per IBM .NET client documentation—property names for key repository mirror Java trustStore concepts. Linux containers use PEM or PKCS12 mounts. Windows may use certificate store APIs. Mutual TLS requires client cert trusted by server SSLPEERMAP. Cipher mismatch fails at connect with XMSException wrapping MQ reason.

Async and Performance

.NET async patterns should not share one session across uncoordinated threads unless documented thread-safe. Pool connections for web request handlers—creating factory per HTTP request adds latency. Batch consumers use dedicated background tasks with long-lived session. Measure end-to-end latency including TLS handshake on cold start after scale-out events.

Troubleshooting

1. Enable MQ trace for .NET per IBM KB for short reproduction windows.
2. Inspect InnerException for MQ reason codes.
3. DISPLAY CHSTATUS on server when .NET reports connection broken.
4. Verify amqmdnet bitness matches process x64 versus x86.
5. Confirm firewall from container subnet to listener.

Explainer: C# Translator for MQ

XMS .NET is the translator between C# business code and IBM MQ wire language—the same translator Java JMS uses with different accent.

Explain Like I'm Five: .NET Client

Your C# game uses a helper DLL to mail letters to the MQ post office—the helper knows the address from settings your team configures.

Practice Exercises

Exercise 1

List Hashtable properties for ORDERS.API on QM1 at mqhost(1414) client mode.

Exercise 2

Design ASP.NET Core registration for singleton ConnectionFactory with reconnect.

Exercise 3

Explain why app pool recycle without disconnect stresses SVRCONN MAXINST.

Frequently Asked Questions

Test Your Knowledge