System
2.0.0.0
4.0.0.0
System.Object
The class is used by applications to produce traces that can be associated with the application. provides tracing methods that allow you to easily trace events, trace data, and issue informational traces. Trace output from can be controlled by configuration file settings. The configuration file is located in the folder with the application executable and has the name of the application with the .config file name extension added. For example, the name of the configuration file for TraceSourceSample.exe is TraceSourceSample.exe.config. The configuration file can be used to determine where the trace information is to be sent and what levels of activity are to be traced. The following example shows the contents of a sample application configuration file.
<configuration>
<system.diagnostics>
<sources>
<source name="TraceTest" switchName="SourceSwitch"
switchType="System.Diagnostics.SourceSwitch" >
<listeners>
<add name="console" />
<remove name ="Default" />
</listeners>
</source>
</sources>
<switches>
<!-- You can set the level at which tracing is to occur -->
<add name="SourceSwitch" value="Warning" />
<!-- You can turn tracing off -->
<!--add name="SourceSwitch" value="Off" -->
</switches>
<sharedListeners>
<add name="console"
type="System.Diagnostics.ConsoleTraceListener"
initializeData="false"/>
</sharedListeners>
<trace autoflush="true" indentsize="4">
<listeners>
<add name="console" />
</listeners>
</trace>
</system.diagnostics>
</configuration>
The class is identified by the name of a source, typically the name of the application. The trace messages coming from a particular component can be initiated by a particular trace source, allowing all messages coming from that component to be easily identified.
defines tracing methods but does not actually provide any specific mechanism for generating and storing tracing data. The tracing data is produced by trace listeners, which are plug-ins that can be loaded by trace sources.
You should not call the tracing methods during finalization. Doing so can result in an being thrown.
You can customize the tracing output's target by adding or removing instances to or from the collection stored in the property. By default, trace output is produced using an instance of the class. The preceding configuration file example demonstrates removing the and adding a to produce the trace output for the trace source. For more information, see <listeners> Element for <source> and <sharedListeners> Element.
Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in try/catch blocks to detect and handle any exceptions from trace listeners.
The class provides the means to dynamically control the tracing output. The preceding configuration file example shows how you can turn off tracing from a trace source and control the level at which tracing occurs. You can modify the value of the source switch without recompiling your application. For information on using the configuration file to set a switch, see and How to: Configure Trace Switches.
If you modify a configuration file while an application is executing, the application must be stopped and restarted or the method must be called before the new settings take effect.
The enumeration is used to define the event type of the trace message. Trace filters use the to determine if a trace listener should produce the trace message.
The trace listeners can optionally have an additional layer of filtering through a trace filter. If a trace listener has an associated filter, the listener calls the method on that filter to determine whether or not to produce the trace information.
The trace listeners use the values of the class properties , , and to format trace output. You can use configuration file attributes to set the , , and properties. The following example sets the property to false and the property to 3.
<configuration>
<system.diagnostics>
<trace autoflush="false" indentsize="3" />
</system.diagnostics>
</configuration>
Provides a set of methods and properties that enable applications to trace the execution of code and associate trace messages with their source.
Constructor
2.0.0.0
4.0.0.0
The source name is used to identify traces. It is used by a to determine whether a trace listener should produce the trace. The recommended practice is to use the name of the application for the source name.
It is not necessary to create a new instance for each trace request. Create one instance and use it for all trace requests for the application.
Initializes a new instance of the class, using the specified name for the source.
The name of the source (typically, the name of the application).
Constructor
2.0.0.0
4.0.0.0
The source name is used to identify traces. It can be used by a to determine if tracing is to occur and by a to determine whether to produce the trace. The default source level is used by an to determine if tracing is to occur based on the source level of the message to be traced.
It is not necessary to create a new instance for each trace request. Create one instance and use it for all trace requests for the application.
Initializes a new instance of the class, using the specified name for the source and the default source level at which tracing is to occur.
The name of the source, typically the name of the application.
A bitwise combination of the enumeration values that specifies the default source level at which to trace.
Property
2.0.0.0
4.0.0.0
System.Collections.Specialized.StringDictionary
To be added.
The property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names.
The following is a sample of a trace source element specifying the custom attribute SecondTraceSourceAttribute:
<sources>
<source name="TraceTest" switchName="TestSourceSwitch"
switchType="Testing.MySourceSwitch, TraceSample"
SecondTraceSourceAttribute="two">
</source>
</sources>
Gets the custom switch attributes defined in the application configuration file.
Method
2.0.0.0
4.0.0.0
System.Void
The method calls the method of each trace listener in the collection.
Closes all the trace listeners in the trace listener collection.
Method
2.0.0.0
4.0.0.0
System.Void
The method calls the method of each trace listener in the collection.
Flushes all the trace listeners in the trace listener collection.
Method
2.0.0.0
4.0.0.0
System.String[]
The default implementation for returns null.
Gets the custom attributes supported by the trace source.
A string array naming the custom attributes supported by the trace source, or null if there are no custom attributes.
Property
2.0.0.0
4.0.0.0
System.Diagnostics.TraceListenerCollection
To be added.
Use this property to access and perform operations on the trace listeners.
Gets the collection of trace listeners for the trace source.
Property
2.0.0.0
4.0.0.0
System.String
To be added.
The name is set by the parameter passed to the constructor or by the trace source name attribute in the configuration file.
The following XML element shows the naming of a trace source in the configuration file.
<configuration>
<system.diagnostics>
<sources>
<source name="TraceTest">
</source>
</sources>
</system.diagnostics>
</configuration>
Gets the name of the trace source.
Property
2.0.0.0
4.0.0.0
System.Diagnostics.SourceSwitch
To be added.
The property allows the filtering of messages before the trace source calls the listeners.
The switch is used to check whether trace calls should be generated or ignored. Each trace method calls the method of the to determine whether to proceed with the trace. If the call returns true, the listeners are called.
Gets or sets the source switch value.
Method
2.0.0.0
4.0.0.0
System.Diagnostics.Conditional("TRACE")
System.Void
The method, like the method, is intended for automated tools, but it also allows the attaching of an additional object, such as an exception instance, to the trace.
The method calls the method of the object returned by the property. If returns true, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods.
The object is limited to a maximum value of 65,535. If the value specified is greater than 65,535, the object uses 65,535.
Writes trace data to the trace listeners in the collection using the specified event type, event identifier, and trace data.
One of the enumeration values that specifies the event type of the trace data.
A numeric identifier for the event.
The trace data.
Method
2.0.0.0
4.0.0.0
System.Diagnostics.Conditional("TRACE")
System.Void
System.ParamArray
The method, like the method, is intended for automated tools, but it also allows the attaching of additional objects, such as an exception instance and a stack trace, to the trace.
The method calls the method of the object returned by the property. If returns true, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods.
The object is limited to a maximum value of 65,535. If the value specified is greater than 65,535, the object uses 65,535.
Writes trace data to the trace listeners in the collection using the specified event type, event identifier, and trace data array.
One of the enumeration values that specifies the event type of the trace data.
A numeric identifier for the event.
An object array containing the trace data.
Method
2.0.0.0
4.0.0.0
System.Diagnostics.Conditional("TRACE")
System.Void
The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source.
The method calls the method of the object returned by the property. If returns true, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods.
The trace content is listener specific. If the method is not overridden by the listener implementation, the default output is the name of the trace source, its numeric identity, and the event type. Additional trace content is dependent upon the listener's property value.
The object is limited to a maximum value of 65,535. If the value specified is greater than 65,535, the uses 65,535.
Writes a trace event message to the trace listeners in the collection using the specified event type and event identifier.
One of the enumeration values that specifies the event type of the trace data.
A numeric identifier for the event.
Method
2.0.0.0
4.0.0.0
System.Diagnostics.Conditional("TRACE")
System.Void
The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source.
The method calls the method of the object returned by the property. If returns true, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods.
The trace content is listener specific. If the method is not overridden by the listener implementation, the default output is the name of the trace source, its numeric identity, the event type, and the message. Additional trace content is dependent upon the listener's property value.
The object is limited to a maximum value of 65,535. If the value specified is greater than 65,535, the object uses 65,535.
Writes a trace event message to the trace listeners in the collection using the specified event type, event identifier, and message.
One of the enumeration values that specifies the event type of the trace data.
A numeric identifier for the event.
The trace message to write.
Method
2.0.0.0
4.0.0.0
System.Diagnostics.Conditional("TRACE")
System.Void
System.ParamArray
For more information about the parameter, see Composite Formatting.
The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source.
The method calls the method of the object returned by the property. If returns true, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods.
The trace content is listener specific. The default method writes the source name, event type, and numeric identity in the trace header, then calls the method, passing the string and array and using the property to format the string as the message output.
The object is limited to a maximum value of 65,535. If the value specified is greater than 65,535, the object uses 65,535.
Writes a trace event to the trace listeners in the collection using the specified event type, event identifier, and argument array and format.
One of the enumeration values that specifies the event type of the trace data.
A numeric identifier for the event.
A composite format string (see Remarks) that contains text intermixed with zero or more format items, which correspond to objects in the array.
An object array containing zero or more objects to format.
Method
2.0.0.0
4.0.0.0
System.Diagnostics.Conditional("TRACE")
System.Void
To be added.
The method provides an informational message intended to be read by users and not by tools.
calls the method, setting to and passing the informative message as the message string. The method in turn calls the method of each trace listener.
Writes an informational message to the trace listeners in the collection using the specified message.
Method
2.0.0.0
4.0.0.0
System.Diagnostics.Conditional("TRACE")
System.Void
System.ParamArray
For more information about the parameter, see Composite Formatting.
The method provides an informational message intended to be read by users and not by tools.
calls the method, setting to and passing the message content as an object array with formatting information. The method in turn calls the method of each trace listener.
Writes an informational message to the trace listeners in the collection using the specified object array and formatting information.
A composite format string (see Remarks) that contains text intermixed with zero or more format items, which correspond to objects in the array.
An array containing zero or more objects to format.
Method
2.0.0.0
4.0.0.0
System.Diagnostics.Conditional("TRACE")
System.Void
The method calls the method of each trace listener in the property to write the trace information. The default method in the base class calls the method to process the call, setting to and appending a string representation of the GUID to .
is intended to be used with the logical operations of a . The parameter relates to the property of a object. If a logical operation begins in one activity and transfers to another, the second activity logs the transfer by calling the method. The call relates the new activity identity to the previous identity. The most likely consumer of this functionality is a trace viewer that can report logical operations that span multiple activities.
Writes a trace transfer message to the trace listeners in the collection using the specified numeric identifier, message, and related activity identifier.
A numeric identifier for the event.
The trace message to write.
A structure that identifies the related activity.