[Windows][Linux]

Installing IBM MQ classes for XMS .NET

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

From IBM MQ 9.2.0, Microsoft.NET Core 3.1 is the minimum required version for running IBM MQ classes for XMS .NET Standard.

[MQ 9.3.0 Jun 2022][MQ 9.3.0 Jun 2022]From IBM MQ 9.3.0, IBM MQ supports .NET 6 applications using IBM MQ classes for XMS .NET Standard. If you are using a .NET Core 3.1 application, you can run this application with a small edit in the csproj file, setting the targetframeworkversion to "net6.0", without any recompilation required.

[MQ 9.3.1 Oct 2022]IBM MQ 9.3.1 provides an XMS .NET client library built against .NET 6 as the target framework. From IBM MQ 9.3.1, 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.

[MQ 9.3.1 Oct 2022]From IBM MQ 9.3.1, the XMS .NET client library built using .NET Standard is available under a new folder netstandard2.0 and 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.

amqmxmsstd.dll library

[MQ 9.3.1 Oct 2022]From IBM MQ 9.3.1, the amqmxmsstd.dll library is available at the following locations
Library built using .NET Standard 2.0 as the target framework
  • [Windows]On Windows: MQ_INSTALLATION_PATH\bin\netstandard2.0.
  • [Linux]On Linux: MQ_INSTALLATION_PATH\lib64\netstandard2.0.
[Deprecated]These libraries are deprecated, and IBM intends to remove them in future releases.
Library built using .NET 6 as the target framework
  • [Windows]On Windows: MQ_INSTALLATION_PATH\bin. The sample applications are installed in MQ_INSTALLATION_PATH/samp/dotnet/samples/cs/core/base.
  • [Linux]On Linux: MQ_INSTALLATION_PATH\lib64. The .NET samples are in MQ_INSTALLATION_PATH/samp/dotnet/samples/cs/core/base.
[MQ 9.3.1 Oct 2022]For IBM MQ 9.3.0 Long Term Support, the IBM MQ classes for XMS .NET Standard library, amqmxmsstd.dll, is available in the following locations:
  • [Windows]On Windows: MQ_INSTALLATION_PATH\bin. The sample applications are installed in MQ_INSTALLATION_PATH/samp/dotnet/samples/cs/core/xms.
  • [Linux]On Linux: MQ_INSTALLATION_PATH/lib64 path. The .NET samples are in MQ_INSTALLATION_PATH/samp/dotnet/samples/cs/core/xms.
For more information, see Installing IBM MQ classes for .NET.
Attention: [Deprecated][MQ 9.3.1 Oct 2022]From IBM MQ 9.3.1, IBM MQ .NET client libraries built using .NET Standard 2.0 as the target framework are deprecated and applications referencing these libraries throw a warning CS0618 during compile time.

[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.

[MQ 9.3.1 Oct 2022]If a .NET Framework application is compiled using amqmdnetstd.dll or amqmxmsstd.dll from a version lower than IBM MQ 9.3.1 and the same application is run using the .NET 6 based IBM MQ client libraries, then the following FileLoadException type of exception is thrown by .NET:
Exception caught: System.IO.FileLoadException: Could not load file or assembly 
'amqmdnetstd, Version=x.x.x.x, 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=x.x.x.x, Culture=neutral, 
PublicKeyToken=23d6cb914eeaac0e'
To resolve this error, the libraries present in MQ_INSTALLATION_PATH/bin/netstandard2.0 must be copied to the directory from where the .NET Framework application is running.

From IBM MQ 9.2.0, 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 Standard and .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 (.NET Standard and .NET 6 libraries).

Table 1. Differences between IBM MQ classes for XMS .NET Framework and IBM MQ classes for XMS .NET (.NET Standard and .NET 6 libraries)
Feature IBM MQ classes for XMS .NET Framework IBM MQ classes for XMS .NET (.NET Standard and .NET 6 libraries)
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.

 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.
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".
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

[MQ 9.3.0 Jun 2022][MQ 9.3.0 Jun 2022]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.