[Windows]

.NET application runtime - Windows only

Considerations when using the .NET application.

The runtime DLL files laid down in the redistributable images on Windows for .NET applications are normally registered with the global assembly cache (GAC) by a user with system administrator privileges, when installing the primary installation. However, this severely limits the benefits of redistribution.

The redistributable package on the Windows platform does not provide any tooling to register DLLs with the GAC, so .NET applications have to locate the appropriate assemblies by other means. There are two options that work in this situation.

Probing

After checking the GAC, the .NET runtime attempts to locate required assemblies through probing. The first location checked is the application base, which is the root location where the application is being run. See the information on How the Runtime Locates Assemblies on the Microsoft Web site for more information.

Note that when using this approach, the maintenance level of the assemblies used when building the .NET application must match those used at runtime - for example an application built at IBM® MQ 8.0.0 Fix Pack 4 must be run with the IBM MQ 8.0.0 Fix Pack 4 redistributable client runtime.

Using this approach, a .NET application placed in the \bin directory alongside the IBM MQ assemblies picks up assemblies from a primary IBM MQ installation (if one exists), falling back to the redistributable copies.
  1. Compile the .NET application under a full IBM MQ installation, that is csc \t:exe \r:System.dll \r:amqmdnet.dll \lib: \out:nmqwrld.exe nmqwrld.cs.
  2. Copy the exe file in the redistributable client .zip file into the \bin directory.

DEVPATH environment variable

An alternative, that allows your application to be built, distributed, extracted and run as previously, is to use DEVPATH to locate the required assemblies. Unlike with the probing approach, this option overrides any matching assemblies from the GAC. However it is for this reason that Microsoft discourages its use in a production environment.

This approach can be effective where there is a possibility that a full IBM MQ installation is installed on the client. However, there is a good reason to always use the redistributable assemblies.
  1. Compile the .NET application under a full IBM MQ installation, that is csc \t:exe \r:System.dll \r:amqmdnet.dll \lib: \out:nmqwrld.exe nmqwrld.cs)
  2. Copy the .exe file into, or alongside, the redistributable client .zip file.
  3. In the same directory as the .exe file, create an application configuration file with the name of the .exe file suffixed by .config, that is nmqwrld.exe.config with the following contents:
    
    <configuration> 
        <runtime>
          <developmentMode  developerInstallation="true" />  
        </runtime>
    </configuration>
    
  4. Call setmqenv -s and set the DEVPATH environment variable to specify the \bin directory from the redistributable image before running the application, that is:
    
    set DEVPATH=%MQ_INSTALLATION_PATH%\bin
    

Starting and stopping trace for the .NET redistributable managed client

There are several different ways to enable trace for IBM MQ .NET applications. For more information, see Tracing IBM MQ .NET applications.

You normally need to use the trace facility only at the request of IBM Support.

More information on .NET

For more information on .NET, see Writing and deploying IBM MQ .NET programs.