XML Configuration

Many of TracerX's configuration properties can be set via XML. The static class Logger.Xml contains the following methods for loading configuration settings from XML.

bool Configure(FileInfo configFile) Reads the TracerX element from the specified XML file. This is the recommended method.
bool Configure() Reads the TracerX element from your application's .config file. More on this later!
bool Configure(Stream configStream) Reads the TracerX element from the specified Stream object.
bool ConfigureAndWatch(FileInfo configFile) Reads the TracerX element from the specified XML file and uses a FileSystemWatcher to monitor the file for changes. If the file changes, it is parsed again.
bool ConfigureFromXml(XmlElement element) Extracts configuration settings from the specified XmlElement. The other methods end up calling this one.

If you use the XML configuration feature, you should call one of the above methods before opening the output file (with Logger.FileLogging.Open() ) since many of the settings are for configuring the output file.

TracerX will log an event if it encounters problems parsing the XML, such as an invalid element. Unless you want this event to go the default event log (the Application event log) using the default source ("TracerX - <exe name>"), you should set the EventLogging.EventLog property before parsing the XML (see Logging Destinations). Therefore, the recommended sequence of calls is...

Logger.EventLogging.EventLog = new EventLog("Your Log", ".", "Your Source"); // Optional
Logger.Xml.Configure(new FileInfo("YourTracerXConfig.xml"));

The following XML sets every TracerX property that can be set via XML, except that additional loggers can also be created and confgured. That is, you need not include every element shown.

<?xml version="1.0" encoding="utf-8" ?>
                <Directory value="%LOCALAPPDATA%" />
                <MaxSizeMb value="10" />
                <Archives value="3" />
                <CircularStartSizeKb value="300" />
                <CircularStartDelaySeconds value="60" />
        <MaxInternalEventNumber value="200" />
        <InternalEventOffset value="1000" />
        <ConsoleFormatString value="{time:HH:mm:ss.fff} {level} {thname} {logger}+{method} {ind}{msg}" />
        <DebugFormatString value="{time:HH:mm:ss.fff} {level} {thname} {logger}+{method} {ind}{msg}" />
        <EventLogFormatString value="{time:HH:mm:ss.fff} {thname} {logger}+{method} {msg}"/>
        <Logger name="Root">
                <filetracelevel value="info" />
                <consoletracelevel value="off" />
                <eventlogtracelevel value="off" />
                <debugtracelevel value="off" />
        <Logger name="StandardData">
                <filetracelevel value="verbose" />

The TracerX element seen above can be in a file of its own or it can be part of your application's .config file. Here's an example of a .config file that includes a TracerX config section.

<?xml version="1.0" encoding="utf-8" ?>
		<section name="TracerX" type="TracerX.XmlConfigSectionHandler, TracerX" />
	        <!-- Inner XML omitted for brevity (same as other example).  /-->	

You must include the <configuration>\<configSections>\<section> element exactly as shown above. The <configuration>\<TracerX> element must follow the same schema as the earlier example.

I feel it's better to put the TracerX configuration in a separate file for the following reasons.
  1. A user could render the application unstartable by introducing syntax errors into the .config file when configuring TracerX.
  2. Some users do not have write access to the Program Files directory, which is where your app and its .config file will normally be.
  3. You may wish to send the user a new TracerX configuration file rather than ask him to edit it in order to enable a higher trace level, change the file size, or whatever. This is easier to do if it is separate from the app .config file.

Last edited Dec 14, 2007 at 5:29 PM by MarkLTX, version 1


No comments yet.