Installing IBM MQ classes for XMS .NET

IBM® MQ classes for XMS .NET, including samples, are installed with IBM MQ on Windows and Linux®.

Installation

[MQ 9.4.0 Jun 2024] IBM MQ 9.4.0 provides an XMS .NET client library built against .NET 6 as the target framework. From IBM MQ 9.4.0, Microsoft .NET 6.0 is the minimum required version for running applications using IBM MQ libraries that are built using .NET 6 as the target framework. The XMS .NET client library built using .NET 6 as the target framework is available under MQ_INSTALLATION_PATH/bin on Windows and under MQ_INSTALLATION_PATH/lib64 on Linux.

[MQ 9.4.0 Jun 2024] From IBM MQ 9.4.0, IBM MQ supports .NET 8 applications using IBM MQ classes for XMS .NET. If you are using a .NET 6 application, you can run this application without any recompilation being required by making a small edit in the runtimeconfig file to set the targetframeworkversion to "net8.0".

[Deprecated] [MQ 9.4.0 Jun 2024] From IBM MQ 9.4.0, in IBM MQ classes for XMS .NET, the methods WriteObject(), ReadObject(), CreateObjectMessage(), and the classes ObjectMessage and XmsObjectMessageImpl used for serialization and deserialization of data are deprecated.

[Removed] [MQ 9.4.0 Jun 2024] The XMS .NET client library built using.NET Standard 2.0, which was deprecated at IBM MQ 9.3.1, has been removed from the product at IBM MQ 9.4.0.

amqmxmsstd.dll library

From IBM MQ 9.4.0, the amqmxmsstd.dll library built using .NET 6 as the target framework is available at the following locations:

On Windows: MQ_INSTALLATION_PATH\bin. The sample applications are installed in MQ_INSTALLATION_PATH/samp/dotnet/samples/cs/core/base.
On Linux: MQ_INSTALLATION_PATH\lib64. The .NET samples are in MQ_INSTALLATION_PATH/samp/dotnet/samples/cs/core/base.

[MQ 9.4.4 Oct 2025] From IBM MQ 9.4.4, you can specify a custom path for TLS certificates used by XMS .NET 6 applications.

[Removed] [MQ 9.4.0 Jun 2024] The XMS .NET client library built using .NET Standard 2.0, which was deprecated at IBM MQ 9.3.1, has been removed from the product at IBM MQ 9.4.0.

Attention: [Removed]

From IBM MQ 9.4.0, XMS .NET client libraries built using .NET Standard 2.0 as the target framework are removed. These libraries were deprecated at IBM MQ 9.3.1.

[Stabilized] All the IBM.XMS.* libraries are still supplied, but these libraries are stabilized; that is, no new features will be introduced into them. For any of the latest features, you must migrate to the amqmxmsstd.dll library. However, you can continue to use the existing libraries on IBM MQ 9.1 Long Term Support or Continuous Delivery releases.

Here are two scenarios that you might encounter following the removal of the netstandard2.0 libraries:

If you are using a IBM MQ classes for XMS .NET Framework application that is built using the netstandard2.0 libraries such as amqmdnetstd.dll, you need to rebuild your application with the Microsoft.NET Framework 4.7.2 libraries such as amqmdnet.dll, in order for your application to run successfully. If you do not rebuild your application, you might get an System.IO.Unexceptionable message:

Exception caught: System.IO.FileLoadException: Could not load file or assembly 'amqmdnetstd, Version=9.3.5.0, Culture=neutral, PublicKeyToken=23d6cb914eeaac0e' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)
File name: 'amqmdnetstd, Version=9.3.5.0, Culture=neutral, PublicKeyToken=23d6cb914eeaac0e'
   at SimplePut.SimplePut.PutMessages()
   at SimplePut.SimplePut.Main(String[] args) in C:\SampleCode\Program.cs:line 132

If you are using a .NET 6 application that is built using netstandard2.0 libraries, then you just need to replace those libraries with the same .NET 6 libraries in the bin folder of the application runtime directory. No rebuild is required.
Note: The replacement .NET 6 library should always be of the same or higher level than the replaced netstandard2.0 library.

The IBM MQ classes for XMS .NET Standard are available for downloading from the NuGet repository. The NuGet package contains both the amqmxmsstd.dll library and the amqmdnetstd.dll library. amqmxmsstd.dll is dependent on amqmdnetstd.dll and, while packaging the XMS .NET Core application, both amqmxmsstd.dll and amqmdnetstd.dll should be packaged along with the XMS .NET Core application. For more information, see Downloading IBM MQ classes for XMS .NET from the NuGet repository.

dspmqver command

You can use the dspmqver command to display version and build information for the .NET Core component.

Comparison between IBM MQ classes for XMS .NET Framework and IBM MQ classes for XMS .NET .NET 6 libraries

The following table lists the features for IBM MQ classes for XMS .NET Framework compared with the features for IBM MQ classes for XMS .NET and .NET 6 libraries).

Table 1. Differences between IBM MQ classes for XMS .NET Framework and IBM MQ classes for XMS .NET
Feature	IBM MQ classes for XMS .NET Framework	IBM MQ classes for XMS .NET
Class Names (APIs)	All classes remain the same in each network.	All classes remain the same in each network.
Operating System	Windows	Windows Dockerized containers Linux macOS
app.config file (Configuration file to enable Trace in redistributable client)	app.config file is used to enable trace for the redistributable package.	app.config is not supported. Use environment variables.
Trace	To trace the XMS .NET client, you can use the existing environment variables, such as the environment variable XMS_TRACE_ON used to enable trace. For more information, see Configuring XMS .NET trace using XMS environment variables. For redistributable clients, the app.config file can be used to enable trace. From IBM MQ 9.4.0, you can enable and disable trace by using the mqclient.ini file and setting the appropriate properties of the Trace stanza. You can also enable and disable tracing dynamically with the mqclient.ini file. For more information, see Tracing XMS .NET applications with mqclient.ini.	To trace the XMS .NET client, you can use the existing environment variables, such as the environment variable XMS_TRACE_ON used to enable trace. For more information, see Configuring XMS .NET trace using XMS environment variables. From IBM MQ 9.4.0, you can enable and disable trace by using the mqclient.ini file and setting the appropriate properties of the Trace stanza. You can also enable and disable tracing dynamically with the mqclient.ini file. For more information, see Tracing XMS .NET applications with mqclient.ini.
Transport Modes	Managed, Unmanaged, and Bindings	Managed
TLS	The Windows keystore is used for storing the certificates.	On Windows, the keystore must be used for storing the certificates. Permitted values are USER or SYSTEM. Based on the input, the IBM MQ .NET client looks at the Windows key store of the current user, or System wide. On Linux, it is recommended to use the X509Store class to install certificates and .NET Core installs certificates to the following location: ".dotnet/corefx/cryptography/x509stores". From IBM MQ 9.4.4, you can add custom paths for storing your TLS certificates and use plain text passwords or the Dotnet Password Encryptor (rundotnetcred) tool for creating encrypted passwords for your certificates. For more information, see Custom path for certificates in XMS .NET for TLS connectivity using plain text or encrypted passwords .
CCDT	Supported	Supported, and the settings of the CCDT path are the same as for .NET Framework classes.
Client auto reconnect	Supported	Supported
Distributed transactions	Supported	Not supported
Installation of dynamic linked libraries (dll's) into the global assembly cache (GAC)	Dll's are installed into the GAC as part of the IBM MQ installation.	Dll's are not installed into the GAC as part of the IBM MQ installation.
Support for WMQ, WPM, and RTT connection types	Supports WMQ, WPM, and RTT connection types	Support for WMQ only
JNDI administered objects	Supports LDAP and FileSystem	Supports FileSystem only

From IBM MQ 9.3.0, to run IBM MQ classes for XMS .NET Framework you must install Microsoft.NET Framework V4.7.2 or later.