Using the MariaDB Connector/Net Trace Source Object
MySQL Connector/Net 6.2 introduced support for .NET 2.0 compatible tracing, using TraceSource objects.
The .NET 2.0 tracing architecture consists of four main parts:
- Source - This is the originator of the trace information. The source is used to send trace messages. The name of the source provided by MariaDB Connector/Net is
MariaDB. - Switch - This defines the level of trace information to emit. Typically, this is specified in the
app.configfile, so that it is not necessary to recompile an application to change the trace level. - Listener - Trace listeners define where the trace information will be written to. Supported listeners include, for example, the Visual Studio Output window, the Windows Event Log, and the console.
- Filter - Filters can be attached to listeners. Filters determine the level of trace information that will be written. While a switch defines the level of information that will be written to all listeners, a filter can be applied on a per-listener basis, giving finer grained control of trace information.
To use tracing a TraceSource object first needs to be created. To create a TraceSource object in MariaDB Connector/Net you would use code similar to the following:
TraceSource ts = new TraceSource('mysql');
To enable trace messages, configure a trace switch. There are three main switch classes, BooleanSwitch, SourceSwitch, and TraceSwitch. Trace switches also have associated with them a trace level enumeration, these are Off, Error, Warning, Info, and Verbose. The following code snippet illustrates creating a switch:
ts.Switch = new SourceSwitch('MySwitch', 'Verbose');
This creates a SourceSwitch, called MySwitch, and sets the trace level to Verbose, meaning that all trace messages will be written.
It is convenient to be able to change the trace level without having to recompile the code. This is achieved by specifying the trace level in application configuration file, app.config. You then simply need to specify the desired trace level in the configuration file and restart the application. The trace source is configured within the system.diagnostics section of the file. The following XML snippet illustrates this:
<configuration> ... <system.diagnostics> <sources> <source name='mysql' switchName='MySwitch' switchType='System.Diagnostics.SourceSwitch' /> ... </sources> <switches> <add name='MySwitch' value='Verbose'/> ... </switches> </system.diagnostics> ... </configuration>
By default, trace information is written to the Output window of Microsoft Visual Studio. There are a wide range of listeners that can be attached to the trace source, so that trace messages can be written out to various destinations. You can also create custom listeners to allow trace messages to be written to other destinations as mobile devices and web services. A commonly used example of a listener is ConsoleTraceListener, which writes trace messages to the console.
To add a listener at run time, use code such as the following:
ts.Listeners.Add(new ConsoleTraceListener());
Then, call methods on the trace source object to generate trace information. For example, the TraceInformation(), TraceEvent(), or TraceData() methods can be used.
The TraceInformation() method simply prints a string passed as a parameter. The TraceEvent() method, as well as the optional informational string, requires a TraceEventType value to be passed to indicate the trace message type, and also an application specific ID. The TraceEventType can have a value of Verbose, Information, Warning, Error, and Critical. Using the TraceData() method you can pass any object, for example an exception object, instead of a message.
To ensure than these generated trace messages gets flushed from the trace source buffers to listeners, invoke the Flush() method. When you are finished using a trace source, call the Close() method. The Close() method first calls Flush(), to ensure any remaining data is written out. It then frees up resources, and closes the listeners associated with the trace source.