Use the stand-alone IBM MQ .NET client

From IBM MQ Version 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 our applications.

About this task

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

• To start and stop trace, use the application configuration file and an IBM MQ specific trace configuration file. Note: The following steps for generating trace apply to the .NET redistributable managed client as well as the stand-alone .NET client.

  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.

  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 our application.) The value of the MQTRACECONFIGFILEPATH property specifies the path for the location of the IBM MQ specific trace configuration file, mqtrace.config, as show 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

• 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 Version 8.0.0, Fix Pack 2 (8.0.0.2) version of the IBM MQ .NET assembly but later a fix pack, IBM MQ Version 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>