Manages writing of logging information in an XML format to a file.

Namespace:  CuttingEdge.Logging
Assembly:  CuttingEdge.Logging (in CuttingEdge.Logging.dll)

Syntax

Visual Basic (Declaration)
Public Class XmlFileLoggingProvider _
	Inherits FileLoggingProviderBase
C#
public class XmlFileLoggingProvider : FileLoggingProviderBase
Visual C++
public ref class XmlFileLoggingProvider : public FileLoggingProviderBase
JavaScript
CuttingEdge.Logging.XmlFileLoggingProvider = function();

Type.createClass(
	'CuttingEdge.Logging.XmlFileLoggingProvider',
	CuttingEdge.Logging.FileLoggingProviderBase);

Remarks

Returning an identifier for the logged event is not appropriate for this provider. This provider will always return null (Nothing in VB) from the Log method.

This class is used by the Logger class to provide Logging services for an application that can write to the file system.

The table below shows the list of valid attributes for the XmlFileLoggingProvider configuration:

AttributeDescription
name The name of the provider. This attribute is mandatory.
description A description of the provider. This attribute is optional.
fallbackProvider A fallback provider that this provider will use when logging failed. The value must contain the name of an existing logging provider. This attribute is optional.
threshold The logging threshold. The threshold limits the number of events logged. The threshold can be defined as follows: Debug < Information < Warning < Error < Critical. i.e., When the threshold is set to Information, events with a severity of Debug will not be logged. When no value is specified, all events are logged. This attribute is optional.
path A relative or absolute path to a file on the file system that will be used to append logging information to. The file will be created when it does not exist. If the file can not be created the provider will fail to initialize. This attribute is mandatory.
The attributes can be specified within the provider configuration. See the example below on how to use.

The XmlFileLoggingProvider checks upon creation whether the configured file can be created and written to. The provider will fail when this is not the case. When the provider is configured in the application's configuration file, it will invalidate the complete provider model. This enables quick detection of a system's misconfiguration.

The XmlFileLoggingProvider does not hold a file lock during the entire life time of the application domain. Instead it will close the file directly after logging an event. This alows other applications to process that file more easily. This however, can lead to a failure when other processes are writing to this file. Writing to that file from outside the context of the XmlFileLoggingProvider or any other type that inherits from the FileLoggingProviderBase is discouraged. Do use the FallbackProvider mechanism to prevent a failure to bubble up the application's call stack.

The following table shows a list of scenario's and for each scenario the table shows whether this scenario can be executed without a change that the provider might fail to log the event.

OperationSafe?
Logging to one XmlFileLoggingProvider instance from a single threaded application.Yes
Logging to one XmlFileLoggingProvider instance in a single AppDomain from multiple threads.Yes
Logging to multiple XmlFileLoggingProvider instances in a single AppDomain that reference all diferent log files.
Logging to multiple XmlFileLoggingProvider instances in a single AppDomain that all reference the same log file.Yes
Logging to mutliple XmlFileLoggingProvider instances in different AppDomains that reference one single log file.No
Writing to the log file outside the context of an XmlFileLoggingProvider instance in that same AppDomain.No
Writing to the log file from within another AppDomain in the same process.No
Writing to the log file from another process.No

Examples

This example demonstrates how to specify values declaratively for several attributes of the Logging section, which can also be accessed as members of the LoggingSection class. The following configuration file example shows how to specify values declaratively for the Logging section.
 Copy Code
  <?xml version="1.0"?>
  <configuration>
      <configSections>
          <section name="logging" type="CuttingEdge.Logging.LoggingSection, CuttingEdge.Logging" />
      </configSections>
      <logging defaultProvider="XmlFileLoggingProvider">
          <providers>
              <add  
                  name="XmlFileLoggingProvider"
                  type="CuttingEdge.Logging.XmlFileLoggingProvider, CuttingEdge.Logging"
                  description="XML file logging provider"
                  threshold="Information"
                  path="log.xml"
              />
          </providers>
      </logging>
  </configuration>
  

Examples

The XmlFileLoggingProvider writes to the configured file by appending new entries to the file one by one, node by node. The XmlFileLoggingProvider will therefore produce a document with multiple root nodes. Because of this the produced document will not be a valid XML document. This is a problem when using this file for automatic analysis using some sort of XML parser.

As workaround to this problem, a user can define a valid XML document that includes the log file by defining an ENTITY that references that file. This way most XML parsers can successfully parse that document.

Below is an example of such a document. The document references a by the XmlFileLoggingProvider produced log file called 'log.xml'.

 Copy Code
  <?xml version="1.0" encoding="utf-8" ?>
  <!DOCTYPE LogEntries [ <!ENTITY Entries SYSTEM "log.xml"> ]>
  <LogEntries>
      &Entries;
  </LogEntries>
  

Examples

The XmlFileLoggingProvider allows to be extended by inheriting from it and overriding the WriteEntryInnerElements(XmlWriter, LogEntry) method. This allows extra information to be writing to the log file or original information to be replaced entirely. Here is an example of a provider that adds a single <MachineName> element to each entry.
 Copy Code
   public class MachineNameXmlFileLoggingProvider : XmlFileLoggingProvider
   {
      protected override void WriteEntryInnerElements(XmlWriter xmlWriter, LogEntry entry)
      {
          base.WriteEntryInnerElements(xmlWriter, entry);
  
          xmlWriter.WriteStartElement("MachineName");
          xmlWriter.WriteValue(Environment.MachineName);
          xmlWriter.WriteEndElement();
      }
   }
    

Inheritance Hierarchy

See Also