Configuring XMS .NET trace using an application configuration file

If you are using IBM® MQ classes for XMS .NET Framework, you can configure trace for XMS .NET applications with an application configuration file. The trace section of this file includes parameters that define what is to be traced, the trace file location and maximum allowed size, the number of trace files used, and the trace file format.

About this task

[V9.1.1 Nov 2018] Using the application configuration file is not supported for IBM MQ classes for XMS .NET Standard. If you are using IBM MQ classes for XMS .NET Standard, you must configure trace from the XMS environment variables. For further details, see Configuring XMS .NET trace using XMS environment variables.

Procedure

To turn on trace using the application configuration file, place the file in the same directory as the executable file for your application.

Trace can be enabled both by component and trace type. It is also possible to turn on trace for an entire trace group. You can turn on trace for components in a hierarchy either individually or collectively. The types of trace available include:

Debug trace
Exception trace
Warnings, informational messages, and error messages
Method entry and exit trace

The following example shows the trace settings defined in the Trace section of an application configuration file:


<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <configSections>
        <sectionGroup name="IBM.XMS">
            <section name="Trace" 
                     type="System.Configuration.SingleTagSectionHandler" />
        </sectionGroup>
    </configSections>

    <IBM.XMS>
        <Trace traceSpecification="*=all=enabled" traceFilePath="" 
               traceFileSize="20000000" traceFileNumber="3" 
               traceFormat="advanced" />
    </IBM.XMS>
 </configuration>

Table 1 describes the parameter settings in more detail.

Table 1. Application configuration file trace parameter settings
Parameter	Description
`traceSpecification=ComponentName=type=state`	`ComponentName` is the name of the class that you want to trace. You can use a * wildcard character in this name. For example, `=all=enabled` specifies that you want to trace all classes, and `IBM.XMS.impl.=all=enabled` specifies that you require API trace only. `type` can be any of the following trace types: all debug event EntryExit `state` can be either enabled or disabled. You can string multiple trace elements together by using a ':' (colon) delimiter.
`traceFilePath=filename`	If you do not specify a traceFilePath, or if the traceFilePath is present but contains an empty string, the trace file is placed in the current directory. To store the trace file in a named directory, specify the directory name in the traceFilePath, for example: `traceFilePath="c:\somepath"`
`traceFileSize=size`	The maximum allowed size of the trace file. When a file reaches this size, it is archived and renamed. The default maximum is 20 MB, which is specified as `traceFileSize=20000000`.
`traceFileNumber=number`	The number of trace files that are to be retained. The default is 4 (one active file and 3 archive files). The minimum number allowed is 2.
`traceFormat=format`	The default trace format is basic. Trace files are produced in this format if you specify `traceFormat=basic`, or if you do not specify a traceFormat, or if the traceFormat is present but contains an empty string. If you require trace that is compatible with trace analyzer tools, you must specify `traceFormat=advanced`.

The trace settings in the application configuration file are dynamic, and are reread every time the file is saved or replaced. If errors are found in the file after it is edited, the trace file settings revert to their default values.