Using the stand-alone IBM MQ .NET client

From IBM® MQ 8.0.0 Fix Pack 2, 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

[Windows][V9.1.1 Nov 2018]From IBM MQ 9.1.1, the amqmdnetstd.dll library is available for .NET Standard support on Windows (see Installing IBM MQ classes for .NET Standard. 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.

[V9.1.2 Mar 2019][Linux]From IBM MQ 9.1.2, the amqmdnetstd.dll library is also available on Linux.

About this task

From IBM MQ 8.0.0 Fix Pack 2, you can build your IBM MQ .NET applications on a machine where the full IBM MQ client is installed and later package the IBM MQ .NET assembly, that is, amqmdnet.dll, along with your application and deploy it on production systems.

The applications that you build and deploy can be the traditional Windows .NET applications, Services, or Microsoft Azure Web/Worker applications.

In such deployments, the IBM MQ .NET client supports only the managed mode of connectivity to a queue manager. The server bindings and unmanaged client mode connectivity are not available as these two modes require a full IBM MQ client installation. Any attempt to use these other two modes results in an application exception.

Procedure

Referencing the IBM MQ .NET client assembly in applications

  • Reference the amqmdnet.dll assembly in your application in the same way that you did for earlier releases.
    Set the CopyLocal property of the amqmdnet assembly to True to ensure that the amqmdnet 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 by using an application configuration file

  • To start and stop trace, use the application configuration file and an IBM MQ specific trace 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:
    • These steps for generating trace apply to the .NET redistributable managed client as well as the stand-alone .NET client.
    • [V9.1.1 Nov 2018]The application configuration file is not supported in .NET Standard. To enable trace on IBM MQ .NET Standard, you use the MQDOTNET_TRACE_ON environment variable.
    Application configuration file (app.config or web.config)
    Applications need to define the MQTRACECONFIGFILEPATH property under the <appSettings> section of the application configuration file, that is, the app.config or web.config file. (The actual name of the application configuration file depends on the name of your application.) The value of the MQTRACECONFIGFILEPATH property specifies the path for the location of the IBM MQ specific trace configuration file, mqtrace.config, as shown in the following example:
    
    <appSettings>
    <add key="MQTRACECONFIGFILEPATH" value="C:\MQTRACECONFIG" />
    </appSettings>
    
    Tracing is disabled if the mqtrace.config file is not found in the path that is specified application configuration file. However, First Failure Support Technology (FFST) and error logs are created in the application's directory, if the application has authority to write to the current directory.
    IBM MQ specific trace configuration file (mqtrace.config)
    The mqtrace.config file is an XML file that defines properties for starting and stopping trace, the path to the trace files, and the path to the error logs. The following table describes these properties.
    Table 1. Properties defined in the mqtrace.config file
    Attribute Description
    MQTRACELEVEL

    0: Stops tracing - this is the default value.

    1: Starts tracing with lesser details.

    2: Starts tracing with full details - recommended.

    MQTRACEPATH Points to a folder where the trace files will be created. The current directory of the application is used if the path is blank or the MQTRACEPATH attribute is not defined.
    MQERRORPATH Points to a folder where error log files will be created. The current directory of the application is used if the path is blank or the MQERRORPATH attribute is not defined.
    The following example shows a sample mqtrace.config file:
    
    <?xml version="1.0" encoding="utf-8"?>
    <traceSettings>
      <MQTRACELEVEL>2</MQTRACELEVEL>
      <MQTRACEPATH>C:\MQTRACEPATH</MQTRACEPATH>
      <MQERRORPATH>C:\MQERRORLOGPATH</MQERRORPATH>
    </traceSettings>
    

    Tracing can be started and stopped dynamically when an application is running by altering the value of the MQTRACELEVEL attribute in the mqtrace.config file.

    The running application must have create and write permissions for the folder specified by the MQTRACELEVEL attribute for generating trace files. Applications that are running in an Microsoft Azure PaaS environment must also ensure similar access permissions since web applications that use an IBM MQ .NET assembly running in Microsoft Azure PaaS might not have create and write permissions. The generation of the trace, first failure data capture (FDC), and error logs fails if the application does not have the required create and write permissions for the specified folder.

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>