IBM Support

XMS .NET – An Overview

Product Documentation


This article provides an overview of the IBM Message Service API for .NET


This article provides an overview of the IBM® Message Service API for .NET, which is known informally as XMS .NET. By the end of this article, you should understand what XMS is, what it can do for you, and when it is appropriate to use XMS for your messaging projects and some best practices.

You should have some familiarity with message-oriented middleware concepts such as point-to-point and publish/subscribe (pub/sub) messaging.

XMS .NET Features
XMS .NET is a programming API available in C# (and other languages supported by the .NET Framework) that provides simple and consistent access to IBM messaging servers. These servers include WebSphere® MQ, WebSphere Message Broker and the Default Messaging Provider in WebSphere Application Server V6 and above.

XMS offers the following features:

Point-to-point messaging

    Like JMS, XMS provides integral support for point-to-point and pub/sub messaging, the two generally recognized messaging styles in the enterprise messaging arena.
    In point-to-point messaging, applications communicate by putting messages out to queues and receiving messages from queues. A message is typically delivered only once.

Pub/sub messaging
    In pub/sub messaging, publishing applications publish messages on topics, and subscriber applications receive those messages after registering an interest in the topic. An intermediary broker ensures that all subscribers to a topic receive the messages published on that topic.
    XMS and JMS reduce the complexity of pub/sub messaging by hiding the way that the underlying messaging provider makes publications or registers subscriptions. An application programmer need not learn the inner workings of different messaging providers, but instead simply sends or receives messages to or from topics.

Request/Reply messaging
    Many messaging applications are based on algorithms that send a request message and then wait for a reply. XMS provides a class called Requestor to help with the development of this style of application. Applications can use this class to create a request message to destination and wait for a response. XMS internally creates the queues required for receiving response and deletes when the Requestor object is disposed.

Automatic Client Reconnection
    Prior to XMS .NET v2.1.0, applications had to implement code to handle exceptions due to connection errors and establish connection to queue manager again if required. XMS .NET v2.1.0 now provides an option where applications let XMS to handle connection errors and reconnect automatically to the same queue manager or another queue manager. All the queue manager resources will be recreated after reconnection. Please refer to the XMS .NET product documentation in IBM Knowledge Center for more details:

WebSphere MQ XA Transaction
    Prior to XMS .NET v2.1.0, XMS allowed local transactions only meaning transactions were limited to just one resource like WebSphere MQ queue manager. XMS .NET v2.1.0 can now participate in global transactions involving WebSphere MQ and other resource managers like Microsoft SQL Server, IBM DB2 UDB etc. It should be noted that the global transaction is controlled through Microsoft Distributed Transaction Coordinator (MSDTC).

Synchronous/asynchronous delivery
    XMS .NET offers a choice of synchronous and asynchronous styles for receiving messages.

    To get a message synchronously, an application calls the receive() verb, which returns a message if one is available.

    To get messages asynchronously, an application registers a MessageListener object with a MessageConsumer. When a MessageListener object has been registered, XMS starts a thread (one thread per session) to listen in the background for new messages. Each time a message needs to be delivered to the MessageConsumer, the registered MessageListener's onMessage() method is called on the background thread.

Message selectors
    Both JMS and XMS let you filter messages using SQL92 selection criteria defined when a MessageConsumer is created. Message selection is performed based on header property values that are set in messages.

    For example, in the following code fragment, an XMS application string property named Postcode in a message. The property value is SO21 2JN (the postcode for the IBM Hursley lab).
    Message.SetProperty(“PostCode”,”SO21 2JN”);

    In the fragment shown below, a receiving application creates a MessageConsumer that filters for postcodes beginning with SO21. This matches the postcode property set in the message, so the message is delivered to this MessageConsumer.

    messageConsumer = session.CreateConsumer(destination,”Postcode LIKE ‘S021%’“);

Message Streaming
    XMS makes use of the message streaming feature of WebSphere MQ server. When this feature is enabled, non-persistent messages are sent down to buffer at client ahead of application requesting them. Because of this application will see better performance when receiving non-persistent messages.

    Message streaming is particularly effective for destinations with a large number of messages that need to be consumed rapidly. Message streaming is not applicable to persistent messages because if the persistent messages are streamed to a buffer, the queue manager would not be able to recover messages following a failure.

Asynchronous Message Put (a.k.a Fire & Forget)
    When an application sends messages to a destination, the destination can be configured so that, when the application calls send(), XMS forwards the message to the queue manager and returns control back to the application without determining whether the queue manager has received the message safely. XMS can work in this way only for non-persistent messages and for persistent messages sent in a transacted session.
    This optimization is of most benefit to an application that connects to a queue manager in client mode and needs to send a sequence of messages in rapid succession, but does not require immediate feedback from the queue manager for each message sent.

Shared Conversations
    Prior to WebSphere MQ v7.0, if a WebSphere MQ client application connected to a queue manager more than once using the same MQI channel, each instance of the MQI channel required a separate TCP connection. In WebSphere MQ V7.0 or later, each connection to the queue manager using the same MQI channel can share a single TCP connection. This arrangement means that fewer network resources are required and the total time taken to create multiple connections to the queue manager is reduced, particularly when using SSL because the SSL handshake takes place only once at the start of the TCP connection.

    XMS exploits this enhancement. For an application that connects to a queue manager in client mode, XMS might create more than one connection to a queue manager using the MQI channel whose name is specified as a property of the IConnectionFactory object. Each of these connections to the queue manager can now share a single TCP connection. The number of connections to queue manager sharing one TCP connection depends on the Shared Conversation Value (SHARECNV) setting on the MQI channel.

    Each IConnection and ISession instances creates connection to a queue manager using the MQI channel. Depending on the SHARECNV setting, an ISession instance may create a new TCP connection. For example if SHARECNV value is 10, then the first IConnection instance creates a TCP socket to queue manager. Another 9 IConnection or ISession instances can share the same socket. Any new IConnection or ISession instance will create a new TCP socket to queue manager.

Poison message handling
    Sometimes, a badly-formatted message arrives on a queue. A badly-formatted means that the receiving application cannot process the message correctly. Such a message can cause the receiving application to fail and to back out this badly-formatted message. The message can then be repeatedly delivered to the input queue and repeatedly backed out by the application. These messages are known as poison messages. XMS detects such poison messages and reroutes them to an alternative destination using the two queue properties, BOQNAME and BOTHRESH.

    If BOQNAME and BOTHRESH are not defined for a queue, XMS attempts to move the poison messages to the dead letter queue of the queue manager. If a dead letter queue has not been defined, then poison messages are repeatedly delivered to application.

Decoupled administration
    XMS and JMS applications use a number of resources (including message servers, queues, and topics), and have a facility to loosely couple the applications to the resources by looking up JMS resource definitions in a directory at run time. In JMS, this facility is implemented using the Java™ Naming and Directory Interface (JNDI).

    JMS resource definitions are stored in either LDAP, file system based, or COS naming JNDI directories, and are configured using either the WebSphere MQ Explorer or the WebSphere Administration Console.

    The main advantage of configuring resource definitions independently from an application is that the application can be targeted at a different server or destination simply by altering a resource definition. You do not need to change, rebuild, and redeploy the application.

    XMS emulates the Java JNDI lookup capability by providing methods to look up objects in LDAP and file system based directories. The lookup can refer to exactly the same administered objects as a Java application, so you do not need to administer separate sets of resources for XMS and JMS. Resources can be defined once and used at run time by a system consisting of a mixture of JMS and XMS applications.

XMS connectivity
IBM offers three main messaging products, each with a set of distinct messaging capabilities implemented by different transports. Each transport has its own wire protocol and is particularly suited to a specific task.
XMS offers a single API that complements JMS by allowing C, C++, and .NET applications to make direct connections to all of these messaging servers. The messaging servers are:
    WebSphere MQ
    WebSphere MQ provides enterprise standard messaging and queuing. It provides both point-to-point and Publish/Subscribe style of messaging.

    WebSphere Message Broker v6.0
    The WebSphere Message Broker exploit and extend WebSphere MQ by adding message routing, transformation, and more sophisticated pub/sub capabilities. Pub/Sub messaging is provided through the Real-Time Transport (RTT) node. RTT is a very fast, lightweight, non-persistent (non-queued), pub/sub protocol. As its name suggests, RTT is most useful when data is required in real-time.

    RTT node has been deprecated in WebSphere Message Broker v7 and above. XMS .NET users are recommended to use WebSphere MQ v7 or later for Pub/Sub messaging.

    WebSphere Application Server V6 or later Default Message Provider
    WebSphere Application Server V6 introduces a new, pure Java message provider that runs in the application server process and takes advantage of application server clustering and administration.

XMS Usage Scenarios
    When applications need to be loosely coupled to servers or destinations
    As discussed in the "XMS Features" section above, XMS enables an application to be loosely coupled to the resources it uses. Loose coupling provides the flexibility to target an application at a different messaging server, destination, or even transport without the need to recompile and redeploy it.

    When Java and non-Java environments need to be integrated
    XMS is a good API choice when integrating Java and non-Java environments via the WebSphere family of messaging servers, because:
    • XMS offers JMS compatibility and the potential for reuse of JMS design and programming skills.
    • XMS simplifies application management in mixed Java and non-Java messaging applications, because JMS and XMS applications can share the same resources. Changes to an administered object will automatically be reflected for both the Java JMS and non-Java XMS applications that use it.
    • XMS is the only non-Java API that provides access to the WebSphere Platform Messaging server and to WebSphere Message Broker Real-Time.

    To access strategic assets from a managed .NET environment
    XMS provides the ideal bridge for integrating .NET applications with applications using the WebSphere family of messaging servers. .NET client applications can be developed and deployed into the managed .NET environment, and can then use XMS to leverage the enterprise-level reliability and scalability of WebSphere servers – for example to access applications running on a mainframe.

Best Practices
XMS .NET API is a simple API for messaging. The following best practices help in building well designed and robust applications.
    Code applications to continually process messages
    When writing an XMS application, consider pulling messages off the queue as soon as possible and deciding whether to process them immediately or to send them to a failure queue. Do not design the application code that requires messages to be cleared (such as messages that are not in the anticipated format) or needs administrator intervention prior to the application being able to process additional messages off of the queue.

    Close and disconnect connections properly
    Code applications to properly close or dispose XMS objects that are no longer used. Failure to do so, especially IConnection or ISession instances, may limit the number connections to a queue manager.

    Keeping connection/session open
    Keep the connection and session open for a longer period if your application sends or receive message continuously. Creation of connection or session is a time consuming operation and consumes lot of resources and involves network flow (for client connections).

    Session and other objects create from session object can’t be used across threads. Instead create session objects on a per thread basis. The only operation that is thread safe is Session.Close().

    Exception handling
    Design your applications to take advantage of exceptions thrown by XMS. An exception handling mechanism like a try/catch block helps in diagnosing issues.

    A XMS exception can contain a number of linked exceptions that provides more details of exceptions thrown at lower layers of XMS.

    It’s recommended to set an Exception listener as soon as an IConnection instance is created. Exception listener catches all the exceptions that arise due connection errors like network failure, queue manager failure etc. Exception listener can be optionally set to catch other types of exception also. This is quite useful diagnosing issues related message listener.

XMS .NET Performance Reports
XMS .NET has published performance reports for a number of typical usage scenarios when using WebSphere MQ as messaging provider. More details on the report can be found at MP7K: WebSphere MQ - XMS .Net with MQ V7.1 Performance Evaluations.

How to get XMS .NET
XMS .NET now ships as part of WebSphere MQ clients. Customers must install WebSphere MQ clients to use XMS .NET. WebSphere MQ client can be downloaded from here:
MQ v9.0
MQ v8.0
MQ v7.5
MQ v7.1

If your XMS .NET application intends to connects to WebSphere MQ v7.1 or later queue manager, then it is recommended to use the XMS .NET that is installed as part of WebSphere MQ v7.1 or later. The XMS .NET which is installed as part of WebSphere MQ 7.1 or later also provides connectivity to
  1. WebSphere MQ v7.0.1 or earlier in client mode.
  2. WebSphere Message Broker v6
  3. Default Messaging provider of WebSphere Application Server v6.0 or later.

This article has explained the features of XMS, and shown how on-the-wire compatibility with JMS and connectivity to the range of IBM messaging servers makes XMS an ideal choice for integrating .NET applications with WebSphere MQ and J2EE infrastructures.

[{"Product":{"code":"SSFKSJ","label":"WebSphere MQ"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":".NET","Platform":[{"code":"PF033","label":"Windows"}],"Version":"9.0;8.0;7.5;7.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym


Document Information

Modified date:
17 June 2018