EventSchemaTraceListener Class
Directs tracing or debugging output of end-to-end events to an XML-encoded, schema-compliant log file.
Assembly: System.Core (in System.Core.dll)
Note: |
|---|
The HostProtectionAttribute attribute applied to this type or member has the following Resources property value: MayLeakOnAbort | Synchronization. The HostProtectionAttribute does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the HostProtectionAttribute class or SQL Server Programming and Host Protection Attributes. |
The EventSchemaTraceListener class provides tracing of end-to-end schema-compliant events. You can use end-to-end tracing for a system that has heterogeneous components that cross thread, AppDomain, process, and computer boundaries. A standardized event schema (see Event Representation for Event Consumers) has been defined to enable tracing across these boundaries. This schema is shared by various tracing technologies, including Windows Vista diagnostics tools such as Event Viewer. The schema also enables the addition of custom, schema-compliant elements.
EventSchemaTraceListener is tuned for logging performance with implicit support for lock-free tracing.
The EventSchemaTraceListener class converts tracing and debugging information into an XML-encoded text stream. The description of the XML output is shown in the tables later in this section.
You can enable or disable an EventSchemaTraceListener object through the application configuration file, and then use the configured EventSchemaTraceListener object in your application. Alternately, you can create an EventSchemaTraceListener object in your code. We recommend that you enable trace listeners through the application configuration file. For information about application configuration files, see Configuring Applications. For information about the use of configuration files for tracing and debugging, see Trace and Debug Settings Schema.
To configure an EventSchemaTraceListener object, modify the configuration file that corresponds to the name of your application. In this file, you can add, remove, or set the properties for a listener. The configuration file should be formatted as follows:
<configuration>
<system.diagnostics>
<sources>
<source name="TestSource" >
<listeners>
<!--Remove the default trace listener for better performance.-->
<remove name="Default"/>
<!--Note: Removing the default trace listener prevents the dialog box
from being displayed for Debug.Fail or Debug.Assert commands that are
executed in user mode.-->
<add name="eventListener"
type="System.Diagnostics.EventSchemaTraceListener, system.core"
initializeData="TraceOutput.xml"
traceOutputOptions="ProcessId, DateTime, Timestamp"
bufferSize="65536"
maximumFileSize="20480000"
logRetentionOption="LimitedCircularFiles"
maximumNumberOfFiles="2"/>
</listeners>
</source>
</sources>
</system.diagnostics>
The EventSchemaTraceListener class inherits the Filter property from the base class TraceListener. The Filter property allows for an additional level of trace output filtering at the listener. If a filter is present, the Trace methods of the trace listener call the ShouldTrace method of the filter to determine whether to emit the trace.
If an attempt is made to write to a file that is being used or is unavailable, a GUID suffix is automatically added to the file name.
Note: |
|---|
Listener methods are intended to be called by methods of the Debug, Trace, and TraceSource classes. Do not call the listener methods directly from application code. The EventSchemaTraceListener listener is primarily intended for use by the TraceSource class. |
The following table describes the elements and attributes of the XML output.
Element | Attributes | Output | Notes |
|---|---|---|---|
CallStack | None | Depends on the presence of the Callstack flag in the TraceOutputOptions property. | Special characters such as > or < are replaced with escape sequences. See the escaped character translation table in the next table. |
Computer | None | Always present. | This element represents the value of the MachineName property. |
Correlation | ActivityID | Always present. | If ActivityID is not specified, the default is an empty GUID. |
RelatedActivityID | Depends on the presence of the relatedActivityId parameter in the Trace method call. | The RelatedActivityID attribute corresponds to the relatedActivityId parameter of the TraceTransfer method. | |
Data | None | Always present. | This element represents parameter input (data). One element is provided for each data object. In the case of event logs, the Data element contains escaped XML data. In the case of data logs, the Data element contains unescaped data. The data log output uses the ToString method of the passed-in data objects. |
Event | None | Always present. | This element contains a trace event. |
EventData | None | Present for event logs. | This element represents parameter input (message, args). It contains Data elements with escaped XML data that is created by calling the TraceEvent method. |
EventID | None | Always present. | This element represents parameter input (id). |
Execution | ProcessID | Depends on the presence of the ProcessId flag in the TraceOutputOptions property. | The ProcessID attribute is specified in the TraceEventCache. On the Microsoft Windows 98 and Windows Millenium Edition operating systems, if ProcessID is larger than 2,147,483,647, it is a positive representation of a negative number and should be converted to obtain the correct process identifier. |
ThreadID | Present when ProcessID is present. | The ThreadID attribute is specified in the TraceEventCache. | |
Level | None | Always present. | This element represents parameter input (the numeric value of eventType). Parameter values that are larger than 255 are output as a level 8, which represents TraceEventType.Information. Trace event types Critical, Error, Warning, Information, and Verbose are output as levels 1, 2, 4, 8, and 10, respectively. |
LogicalOperationStack | None | Depends on the presence of the LogicalOperationStack flag in the TraceOutputOptions property. | Only one logical operation can exist. Therefore, the values are written as LogicalOperation nodes under the LogicalOperationStack element. |
OpCode | None | Present when Level is greater than 255. | This element represents Trace event types that have numeric values greater than 255. Start, Stop, Suspend, Resume, or Transfer are output as levels 1, 2, 4, 8, and 10, respectively. |
Provider | GUID | Always present. | Always empty. |
RenderingInfo | Culture | Always present. | This attribute represents a resource string for the event type. It is always "en-EN\". |
System | Name | Always present. | |
TimeCreated | SystemTime | Depends on the presence of the DateTime flag in the TraceOutputOptions property. | The time is the value of the TraceEventCache.DateTime property. This property is expressed as Coordinated Universal Time |
TimeStamp | None | Depends on the presence of the Timestamp flag in the TraceOutputOptions property. | This element is specified in the TraceEventCache. |
UserData | None | Present for data logs. | This element contains Data elements with unescaped, user-provided data from a TraceData method. |
The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes except for the UserData element, which contains user-provided, unescaped data. The UserData element is a result of calls to the TraceData method.
Escaped character | Value |
|---|---|
& | & |
< | < |
> | > |
" | " |
\ | ' |
0xD | 
 |
0xA | 
 |
The following code example demonstrates how to use the EventSchemaTraceListener class.
#Const NOCONFIGFILE = True Imports System Imports System.IO Imports System.Xml Imports System.Xml.XPath Imports System.Diagnostics Class testClass <STAThreadAttribute()> _ Shared Sub Main() File.Delete("TraceOutput.xml") Dim ts As New TraceSource("TestSource") #If NOCONFIGFILE Then ts.Listeners.Add(New EventSchemaTraceListener("TraceOutput.xml", "eventListener", 65536, TraceLogRetentionOption.LimitedCircularFiles, 20480000, 2)) ts.Listeners("eventListener").TraceOutputOptions = TraceOptions.DateTime Or TraceOptions.ProcessId Or TraceOptions.Timestamp #End If ts.Switch.Level = SourceLevels.All Dim testString As String = "<Test><InnerElement Val=""1"" /><InnerElement Val=""Data""/><AnotherElement>11</AnotherElement></Test>" Dim unXData As New UnescapedXmlDiagnosticData(testString) ts.TraceData(TraceEventType.Error, 38, unXData) ts.TraceEvent(TraceEventType.Error, 38, testString) ts.Flush() ts.Close() DisplayProperties(ts) Process.Start("notepad.exe", "TraceOutput.xml") Console.WriteLine("Press the enter key to exit") Console.ReadLine() End Sub 'Main Private Shared Sub DisplayProperties(ByVal ts As TraceSource) Console.WriteLine("IsThreadSafe? " + CType(ts.Listeners("eventListener"), EventSchemaTraceListener).IsThreadSafe.ToString()) Console.WriteLine("BufferSize = " + CType(ts.Listeners("eventListener"), EventSchemaTraceListener).BufferSize.ToString()) Console.WriteLine("MaximumFileSize = " + CType(ts.Listeners("eventListener"), EventSchemaTraceListener).MaximumFileSize.ToString()) Console.WriteLine("MaximumNumberOfFiles = " + CType(ts.Listeners("eventListener"), EventSchemaTraceListener).MaximumNumberOfFiles.ToString()) Console.WriteLine("Name = " + CType(ts.Listeners("eventListener"), EventSchemaTraceListener).Name) Console.WriteLine("TraceLogRetentionOption = " + CType(ts.Listeners("eventListener"), EventSchemaTraceListener).TraceLogRetentionOption.ToString()) Console.WriteLine("TraceOutputOptions = " + CType(ts.Listeners("eventListener"), EventSchemaTraceListener).TraceOutputOptions.ToString()) End Sub End Class 'testClass
System.MarshalByRefObject
System.Diagnostics.TraceListener
System.Diagnostics.TextWriterTraceListener
System.Diagnostics.EventSchemaTraceListener
Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Note: