Installing IBM MQ classes for .NET

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

Prerequisites and installation

From IBM MQ 9.2.0, the IBM MQ .NET client library built using .NET Standard is available on Windows and Linux. To run IBM MQ classes for .NET Standard, you must install Microsoft .NET Core. Microsoft.NET Core 3.1 is the minimum required version for running IBM MQ classes for .NET Standard.

[MQ 9.3.0 Jun 2022] From IBM MQ 9.3.0, IBM MQ supports .NET 6 applications using IBM MQ classes for .NET Standard.

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

The latest version of IBM MQ classes for .NET is installed by default as part of the standard IBM MQ installation in the Java and .NET Messaging and Web Services feature.

For more information about prerequisites and installation on Windows:

See Requirements for IBM MQ classes for .NET, for the prerequisite software to run IBM MQ classes for .NET.
See Installing IBM MQ server on Windows or Installing an IBM MQ client on Windows systems for installation instructions.

For more information about prerequisites and installation on Linux:

See Requirements for IBM MQ classes for .NET, for the prerequisite software to run IBM MQ classes for .NET.
For rpm installation instructions, see Installing an IBM MQ client on Linux systems.
For Linux Ubuntu, using Debian packages, see Installing an IBM MQ client on Linux systems.

The IBM MQ classes for .NET Standard library, amqmdnetstd.dll, is available for downloading from the NuGet repository. For more information, see Downloading IBM MQ classes for .NET from the NuGet repository.

amqmdnetstd.dll library

From IBM MQ 9.3.1, the amqmdnetstd.dll library is available at the following locations

Library built using .NET Standard 2.0 as the target framework

On Windows: MQ_INSTALLATION_PATH\bin\netstandard2.0.
On Linux: MQ_INSTALLATION_PATH\lib64\netstandard2.0.

These libraries are deprecated, and IBM intends to remove them in future releases.

Library built using .NET 6 as the target framework

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.

For IBM MQ 9.3.0 Long Term Support, the amqmdnetstd.dll library is available in 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 path. The .NET samples are in MQ_INSTALLATION_PATH/samp/dotnet/samples/cs/core/base.

Attention: [Deprecated]

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] [MQ 9.3.1 Oct 2022] The amqmdnet.dll library for .NET Framework is still supplied, but this library is stabilized; that is, no new features will be introduced into it. For any of the latest features you must migrate to the amqmdnetstd.dll library. However, you can continue to use the amqmdnet.dll library on IBM MQ 9.1 or later Long Term Support or Continuous Delivery releases.

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.

dspmqver command

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

Feature comparison between IBM MQ classes for .NET Framework and IBM MQ classes for .NET (.NET Standard and .NET 6 libraries)

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

Table 1. Differences between IBM MQ classes for .NET Framework and IBM MQ classes for .NET (.NET Standard and .NET 6 libraries)
Feature	IBM MQ classes for .NET Framework	IBM MQ classes for .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 and stand-alone IBM MQ .NET client. See Tracing an IBM MQ classes for .NET Framework client using an application configuration file for more information on the variables you use for trace, including MQTRACEPATH and MQTRACELEVEL.	app.config is not supported. Use environment variables.
Trace	For a full client installation of IBM MQ, you can use the strmqtrc command to enable trace for IBM MQ classes for .NET Framework. For redistributable clients, the app.config file is also used to enable trace. For more information, see Tracing IBM MQ .NET applications. From IBM MQ 9.3.3, 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 IBM MQ .NET applications with mqclient.ini.	The environment variable MQDOTNET_TRACE_ON is used to enable trace for redistributable clients. Values equal to and less than 0 do not enable trace. A value of 1 enables default level tracing. A value greater than 1, enables detailed tracing. Setting this environment variable to any other value like string does not enable trace. See Tracing IBM MQ .NET applications using environment variables. The MQDOTNET_TRACE_ON environment variable checks whether the IBM MQ trace directory is available or not. If the trace directory is available, the trace file is generated in the trace directory. However, if IBM MQ is not installed, the trace file is copied to the current working directory. Other environment variables including MQERRORPATH, MQLOGLEVEL, MQSERVER, and so on, that are used for IBM MQ classes for .NET Framework, can be used and work in the same way. From IBM MQ 9.3.3, 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 IBM MQ .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".
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.

Note: Windows security identifiers (SIDs):

Domain level authentication is not supported for IBM MQ classes for .NET (.NET Standard and .NET 6 libraries). The logged-in user ID is used for authentication.

Developing IBM MQ .NET Core applications on macOS

IBM MQ .NET Core applications can be developed on macOS.

The IBM MQ .NET libraries are not packaged with the macOS toolkit so you must copy them from a Windows or Linux IBM MQ client on to macOS. You can then use these libraries to develop IBM MQ .NET Core applications on macOS.

Once developed, these applications can be run supported on either Windows or Linux environments.