Using the stand-alone IBM MQ .NET client

The IBM® MQ .NET client offers you the ability to package and deploy an IBM MQ .NET assembly without needing to use the full IBM MQ client installation on production systems for running your applications.

Before you begin

From IBM MQ 9.3.1, the amqmdnetstd.dll client library installed in the default location is based on .NET 6. The amqmdnetstd.dll client library based on .NET Standard has been moved to a new location in the IBM MQ client installation package and is now available in the following locations:

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

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.

The amqmdnet.dll library 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 Long Term Support or Continuous Delivery releases.

Referencing the IBM MQ .NET client assembly in applications

• Reference the amqmdnetstd.dll assembly in your application in the same way that you did for earlier releases.
  Set the CopyLocal property of the amqmdnetstd.dll assembly to True to ensure that the amqmdnetstd.dll assembly is copied to the bin directory of the application. Setting this property also helps the application packaging tool to package the required binary files for deployment on production systems as well as Microsoft Azure PaaS cloud environments.

Adding global transaction support

• Ensure that your application deploys the monitor application WMQDotnetXAMonitor on the machine along with the application itself.
  If an application uses the IBM MQ .NET managed global transaction feature, then it must also deploy the WMQDotnetXAMonitor on the machine along with the application itself. This utility is needed for recovering any in-doubt transactions.

Starting and stopping trace

• For IBM MQ classes for .NET Framework only, to start and stop trace using the application configuration file and an IBM MQ specific trace configuration file, see Tracing an IBM MQ classes for .NET Framework client using an application configuration file.

  You must use the application configuration file and an IBM MQ specific trace configuration file because, since there is no full IBM MQ client installation, the standard tools that are used for starting and stopping trace, strmqtrc and endmqtrc, are not available.

  Notes:

  • This way of generating trace applies to the .NET redistributable managed client as well as the stand-alone .NET client. See .NET application runtime - Windows only.
  • The application configuration file is not supported in IBM MQ classes for .NET (.NET Standard and .NET 6 libraries). To enable trace for IBM MQ classes for .NET (.NET Standard and .NET 6 libraries), you use the MQDOTNET_TRACE_ON environment variable. See Tracing IBM MQ .NET applications using environment variables.
• Start and stop trace by using the mqclient.ini file and setting the appropriate properties of the Trace stanza.
  See Tracing IBM MQ .NET applications with mqclient.ini.

  From IBM MQ 9.3.3, you can configure 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.

Enabling binding redirection in the application configuration file

• To enable compile time binding reference of the IBM MQ .NET assembly to a later version of the assembly, add the <dependentAssembly> property to the application configuration file.
  The following example snippet in the app.config file redirects an application that was compiled using the IBM MQ 8.0.0 Fix Pack 2 (8.0.0.2) version of the IBM MQ .NET assembly but later a fix pack, IBM MQ 8.0.0 Fix Pack 3, was then applied that updated IBM MQ.NET assembly to 8.0.0.3.

  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <!-- amqmdnet related binding redirect -->
      <dependentAssembly>
        <assemblyIdentity name="amqmdnet"
                           publicKeyToken="dd3cb1c9aae9ec97"
                           culture="neutral" />
        <codeBase version="8.0.0.2"
              href="file:///amqmdnet.dll"/>
        <bindingRedirect oldVersion="1.0.0.3-8.0.0.2"
                         newVersion="8.0.0.3"/>
        <publisherPolicy apply="no" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>