Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

EventSchemaTraceListener Class

Directs tracing or debugging output of end-to-end events to an XML-encoded, schema-compliant log file.

Namespace:  System.Diagnostics
Assembly:  System.Core (in System.Core.dll)
[HostProtectionAttribute(SecurityAction.LinkDemand, MayLeakOnAbort = true)]
[HostProtectionAttribute(SecurityAction.LinkDemand, Synchronization = true)]
public class EventSchemaTraceListener : TextWriterTraceListener

The EventSchemaTraceListener type exposes the following members.

  NameDescription
Public methodEventSchemaTraceListener(String)Initializes a new instance of the EventSchemaTraceListener class, using the specified file as the recipient of debugging and tracing output.
Public methodEventSchemaTraceListener(String, String)Initializes a new instance of the EventSchemaTraceListener class with the specified name, using the specified file as the recipient of debugging and tracing output.
Public methodEventSchemaTraceListener(String, String, Int32)Initializes a new instance of the EventSchemaTraceListener class with the specified name and specified buffer size, using the specified file as the recipient of debugging and tracing output.
Public methodEventSchemaTraceListener(String, String, Int32, TraceLogRetentionOption)Initializes a new instance of the EventSchemaTraceListener class with the specified name and specified buffer size, using the specified file with the specified log retention policy as the recipient of the debugging and tracing output.
Public methodEventSchemaTraceListener(String, String, Int32, TraceLogRetentionOption, Int64)Initializes a new instance of the EventSchemaTraceListener class with the specified name and specified buffer size, using the specified file with the specified log retention policy and maximum size as the recipient of the debugging and tracing output.
Public methodEventSchemaTraceListener(String, String, Int32, TraceLogRetentionOption, Int64, Int32)Initializes a new instance of the EventSchemaTraceListener class with the specified name and specified buffer size, using the specified file with the specified log retention policy, maximum size, and file count as the recipient of the debugging and tracing output.
Top
  NameDescription
Public propertyAttributesGets the custom trace listener attributes defined in the application configuration file. (Inherited from TraceListener.)
Public propertyBufferSizeGets the size of the output buffer.
Public propertyFilterGets and sets the trace filter for the trace listener. (Inherited from TraceListener.)
Public propertyIndentLevelGets or sets the indent level. (Inherited from TraceListener.)
Public propertyIndentSizeGets or sets the number of spaces in an indent. (Inherited from TraceListener.)
Public propertyIsThreadSafeGets a value indicating whether the trace listener is thread safe. (Overrides TraceListener.IsThreadSafe.)
Public propertyMaximumFileSizeGets the maximum size of the log file.
Public propertyMaximumNumberOfFilesGets the maximum number of log files.
Public propertyNameGets or sets a name for this TraceListener. (Inherited from TraceListener.)
Protected propertyNeedIndentGets or sets a value indicating whether to indent the output. (Inherited from TraceListener.)
Public propertyTraceLogRetentionOptionGets the trace log retention option for the file.
Public propertyTraceOutputOptionsGets or sets the trace output options. (Inherited from TraceListener.)
Public propertyWriterGets or sets the underlying text writer that writes to the log file.
Top
  NameDescription
Public methodCloseCloses the log file for this listener so that it no longer receives tracing or debugging output. (Overrides TextWriterTraceListener.Close().)
Public methodCreateObjRefCreates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
Public methodDispose()Releases all resources used by the TraceListener. (Inherited from TraceListener.)
Protected methodDispose(Boolean)Infrastructure. Disposes this TextWriterTraceListener object. (Inherited from TextWriterTraceListener.)
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public methodFail(String)Emits an error message to the listener you create when you implement the TraceListener class. (Inherited from TraceListener.)
Public methodFail(String, String)Writes error information, including a basic error message and a detailed error message, to the log file. (Overrides TraceListener.Fail(String, String).)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodFlushCauses buffered data to be written to the log for this listener. (Overrides TextWriterTraceListener.Flush().)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetLifetimeServiceRetrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodGetSupportedAttributesGets the custom XML configuration attributes that the trace listener supports. (Overrides TraceListener.GetSupportedAttributes().)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodInitializeLifetimeServiceObtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodMemberwiseClone()Creates a shallow copy of the current Object. (Inherited from Object.)
Protected methodMemberwiseClone(Boolean)Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodTraceData(TraceEventCache, String, TraceEventType, Int32, Object)Writes trace information, a single data object, and event information to the log file. (Overrides TraceListener.TraceData(TraceEventCache, String, TraceEventType, Int32, Object).)
Public methodTraceData(TraceEventCache, String, TraceEventType, Int32, Object[])Writes trace information, multiple data objects, and event information to the log file. (Overrides TraceListener.TraceData(TraceEventCache, String, TraceEventType, Int32, Object[]).)
Public methodTraceEvent(TraceEventCache, String, TraceEventType, Int32)Writes trace and event information to the listener specific output. (Inherited from TraceListener.)
Public methodTraceEvent(TraceEventCache, String, TraceEventType, Int32, String)Writes trace information, a message, and event information to the log file. (Overrides TraceListener.TraceEvent(TraceEventCache, String, TraceEventType, Int32, String).)
Public methodTraceEvent(TraceEventCache, String, TraceEventType, Int32, String, Object[])Writes trace information, a formatted message, and event information to the log file. (Overrides TraceListener.TraceEvent(TraceEventCache, String, TraceEventType, Int32, String, Object[]).)
Public methodTraceTransferWrites trace information, including the identity of a related activity, a message, and event information, to the log file. (Overrides TraceListener.TraceTransfer(TraceEventCache, String, Int32, String, Guid).)
Public methodWrite(Object)Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class. (Inherited from TraceListener.)
Public methodWrite(String)Writes a message to the log file without providing any additional context information. (Overrides TextWriterTraceListener.Write(String).)
Public methodWrite(Object, String)Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class. (Inherited from TraceListener.)
Public methodWrite(String, String)Writes a category name and a message to the listener you create when you implement the TraceListener class. (Inherited from TraceListener.)
Protected methodWriteIndentWrites the indent to the listener you create when you implement this class, and resets the NeedIndent property to false. (Inherited from TraceListener.)
Public methodWriteLine(Object)Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class, followed by a line terminator. (Inherited from TraceListener.)
Public methodWriteLine(String)Writes a message followed by the current line terminator to the log file without providing any additional context information. (Overrides TextWriterTraceListener.WriteLine(String).)
Public methodWriteLine(Object, String)Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class, followed by a line terminator. (Inherited from TraceListener.)
Public methodWriteLine(String, String)Writes a category name and a message to the listener you create when you implement the TraceListener class, followed by a line terminator. (Inherited from TraceListener.)
Top

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. The schema enables the addition of custom, schema-compliant elements. You can use the Service Trace Viewer Tool (SvcTraceViewer.exe) to display the event data.

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 .NET Framework Apps. 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.

NoteNote

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

&

&amp;

<

&lt;

>

&gt;

"

&quot;

\

&apos;

0xD

&#xD;

0xA

&#xA;

NoteNote

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 following code example demonstrates how to use the EventSchemaTraceListener class.

#define NOCONFIGFILE
using System;
using System.IO;
using System.Xml;
using System.Xml.XPath;
using System.Diagnostics;

class testClass
{
    [STAThreadAttribute]
    static void Main()
    {
        File.Delete("TraceOutput.xml");
        TraceSource ts = new TraceSource("TestSource");
#if NOCONFIGFILE
        //ts.Listeners.Add(new EventSchemaTraceListener("TraceOutput.xml", "eventListener", 65536, TraceLogRetentionOption.LimitedCircularFiles, 20480000, 2));
        ts.Listeners.Add(new EventSchemaTraceListener("TraceOutput.xml", "eventListener"));
        ts.Listeners["eventListener"].TraceOutputOptions = TraceOptions.DateTime | TraceOptions.ProcessId | TraceOptions.Timestamp;
#endif
        ts.Switch.Level = SourceLevels.All;
        string testString = "<Test><InnerElement Val=\"1\" /><InnerElement Val=\"Data\"/><AnotherElement>11</AnotherElement></Test>";
        UnescapedXmlDiagnosticData unXData = new UnescapedXmlDiagnosticData(testString);
        ts.TraceData(TraceEventType.Error, 38, unXData);
        ts.TraceEvent(TraceEventType.Error, 38, testString);
        Trace.Listeners.Add(new EventSchemaTraceListener("TraceOutput.xml"));
        Trace.Write("test", "test");
        Trace.Flush();
        ts.Flush();
        ts.Close();
        DisplayProperties(ts);
        Process.Start("notepad.exe", "TraceOutput.xml");
        Console.WriteLine("Press the enter key to exit");
        Console.ReadLine();
    }
    private static void DisplayProperties(TraceSource ts)
    {
        Console.WriteLine("IsThreadSafe? " + ((EventSchemaTraceListener)ts.Listeners["eventListener"]).IsThreadSafe);
        Console.WriteLine("BufferSize =  " + ((EventSchemaTraceListener)ts.Listeners["eventListener"]).BufferSize);
        Console.WriteLine("MaximumFileSize =  " + ((EventSchemaTraceListener)ts.Listeners["eventListener"]).MaximumFileSize);
        Console.WriteLine("MaximumNumberOfFiles =  " + ((EventSchemaTraceListener)ts.Listeners["eventListener"]).MaximumNumberOfFiles);
        Console.WriteLine("Name =  " + ((EventSchemaTraceListener)ts.Listeners["eventListener"]).Name);
        Console.WriteLine("TraceLogRetentionOption =  " + ((EventSchemaTraceListener)ts.Listeners["eventListener"]).TraceLogRetentionOption);
        Console.WriteLine("TraceOutputOptions =  " + ((EventSchemaTraceListener)ts.Listeners["eventListener"]).TraceOutputOptions);
    }
}

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.