System.Diagnostics.TraceListener Class

Summary

Provides the abstract base class for the listeners who monitor trace and debug output.

C# Syntax:

public abstract class TraceListener : MarshalByRefObject, IDisposable

This type is safe for multithreaded operations.

For examples of how to implement a TraceListener, see the DefaultTraceListener, TextWriterTraceListener and the EventLogTraceListener classes.

You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler.

• To enable debugging in C#, add the /d:DEBUG flag to the compiler command line when you compile your code, or you can add #define DEBUG to the top of your file. In Visual Basic, add the /d:DEBUG=True flag to the compiler command line.
• To enable tracing using in C#, add the /d:TRACE flag to the compiler command line when you compile your code, or add #define TRACE to the top of your file. In Visual Basic, add the /d:TRACE=True flag to the compiler command line.

To set the level of your listener, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameter, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted similar to the following example:

          <configuration>
          <system.diagnostics>
              <switches>
                  <add name="MagicTraceSwitch" value="3" />
              </switches>
              <trace autoflush="false" indentsize="4">
                  <listeners>
                     <add name="myListener" type="System.Diagnostics.TextWriterTraceListener,System" initializeData="c:\myListener.log" />
                     <remove type="System.Diagnostics.DefaultTraceListener,System"/> 
                  </listeners>
              </trace>
          </system.diagnostics>
           </configuration>
        

Notes to inheritors: Inherit from this class to implement a custom listener for the Debug and Trace classes. At a minimum, you must implement the TraceListener.Write and TraceListener.WriteLine methods. Additionally, you can implement the TraceListener.Fail, TraceListener.Close and TraceListener.Flush methods.

System.Diagnostics Namespace | DefaultTraceListener | EventLogTraceListener | TextWriterTraceListener | Debug | Trace

System.Diagnostics.TraceListener Member List:

Public Properties

IndentLevel	Read-write Gets or sets the indent level.
IndentSize	Read-write Gets or sets the number of spaces in an indent.
Name	Read-write Gets or sets a name for this TraceListener.

Public Methods

Close	When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output.
CreateObjRef (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.CreateObjRef Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Dispose	Overloaded: Dispose() Releases all resources used by the TraceListener.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
Fail	Overloaded: Fail(string message) Emits an error message to the listener you create when you implement the TraceListener class.
Fail	Overloaded: Fail(string message, string detailMessage) Emits an error message, and a detailed error message to the listener you create when you implement the TraceListener class.
Flush	When overridden in a derived class, flushes the output buffer.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetLifetimeService (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.GetLifetimeService Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
InitializeLifetimeService (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.InitializeLifetimeService Obtains a lifetime service object to control the lifetime policy for this instance.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.
Write	Overloaded: Write(object o) Writes the value of the object's Object.ToString method to the listener you create when you implement the TraceListener class.
Write	Overloaded: Write(string message) When overridden in a derived class, writes the specified message to the listener you create in the derived class.
Write	Overloaded: Write(object o, string category) Writes a category name and the value of the object's Object.ToString method to the listener you create when you implement the TraceListener class.
Write	Overloaded: Write(string message, string category) Writes a category name and a message to the listener you create when you implement the TraceListener class.
WriteLine	Overloaded: WriteLine(object o) Writes the value of the object's Object.ToString method to the listener you create when you implement the TraceListener class, followed by a line terminator.
WriteLine	Overloaded: WriteLine(string message) When overridden in a derived class, writes a message to the listener you create in the derived class, followed by a line terminator.
WriteLine	Overloaded: WriteLine(object o, string category) Writes a category name and the value of the object's Object.ToString method to the listener you create when you implement the TraceListener class, followed by a line terminator.
WriteLine	Overloaded: WriteLine(string message, string category) Writes a category name and a message to the listener you create when you implement the TraceListener class, followed by a line terminator.

Protected Constructors

ctor #1	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the TraceListener class.
ctor #2	Overloaded: .ctor(string name) Initializes a new instance of the TraceListener class using the specified name as the listener.

Protected Properties

NeedIndent

Read-write Gets or sets a value indicating whether to indent the output.

Protected Methods

Dispose	Overloaded: Dispose(bool disposing) Releases the unmanaged resources used by the TraceListener and optionally releases the managed resources.
Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.
WriteIndent	Writes the indent to the listener you create when you implement this class, and resets the TraceListener.NeedIndent property to false.

Hierarchy:

• System.Object
• System.MarshalByRefObject
• System.Diagnostics.TraceListener
  • System.Diagnostics.DefaultTraceListener
  • System.Diagnostics.TextWriterTraceListener

System.Diagnostics.TraceListener Member Details

Summary

Initializes a new instance of the TraceListener class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

protected TraceListener();

The following table shows initial property values for an instance of TraceListener.

Property	Default Value
Name	The empty string ("").
Indent	Zero.
IndentSize	Four spaces.

Return to top

Summary

Initializes a new instance of the TraceListener class using the specified name as the listener.

C# Syntax:

protected TraceListener(    string name );

name

The name of the TraceListener.

Return to top

Summary

Gets or sets the indent level.

C# Syntax:

public int IndentLevel {get; set;}

This property is stored on per-thread/per-request basis.

Return to top

Summary

Gets or sets the number of spaces in an indent.

C# Syntax:

public int IndentSize {get; set;}

The property is stored on per-thread/per-request basis.

Return to top

Summary

Gets or sets a name for this TraceListener.

C# Syntax:

public virtual string Name {get; set;}

The name can be used to organize and access listeners in a TraceListenerCollection collection.

Return to top

Summary

Gets or sets a value indicating whether to indent the output.

C# Syntax:

protected bool NeedIndent {get; set;}

Return to top

Summary

When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output.

C# Syntax:

public virtual void Close();

Use this method when the output is going to a file, such as to the TextWriterTraceListener. After a call to this method, you must reinitialize the object.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.CreateObjRef

Summary

Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.

C# Syntax:

public virtual ObjRef CreateObjRef(    Type requestedType );

requestedType

The Type of the object that the new ObjRef will reference.

Return Value:

Information required to generate a proxy.

Exceptions

Exception Type	Condition
RemotingException	This instance is not a valid remoting object.

Return to top

Summary

Releases all resources used by the TraceListener.

C# Syntax:

public void Dispose();

Implements:

IDisposable.Dispose

Calling TraceListener.Dispose allows the resources used by the TraceListener. to be reallocated for other purposes. For more information about TraceListener.Dispose, see the conceptual topic at MSDN: cleaningupunmanagedresources.

Return to top

Summary

Releases the unmanaged resources used by the TraceListener and optionally releases the managed resources.

C# Syntax:

protected virtual void Dispose(    bool disposing );

disposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.

This method is called by the public Dispose method and the Object.Finalize method.Dispose() invokes the protected Dispose(Boolean) method with the disposing parameter set to true. Object.Finalize invokes Dispose with disposing set to false.

When the disposing parameter is true, this method releases all resources held by any managed objects that this TraceListener references. This method invokes the Dispose() method of each referenced object.

Notes to inheritors: Dispose can be called multiple times by other objects. When overriding Dispose(Boolean), be careful not to reference objects that have been previously disposed of in an earlier call to Dispose. For more information about how to implement Dispose, see the conceptual topic at MSDN: implementingdisposemethod.

For more information about Dispose and Finalize, see the conceptual topic at MSDN: cleaningupunmanagedresources and the conceptual topic at MSDN: overridingfinalizemethod.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Emits an error message to the listener you create when you implement the TraceListener class.

C# Syntax:

public virtual void Fail(    string message );

message

A message to emit.

The default behavior is to display the specified message in a message box when the application is running in a user-interface mode, and to the TraceListener instances in a TraceListenerCollection collection. By default, the TraceListenerCollection collection has an instance of a DefaultTraceListener. You can customize this behavior by adding a TraceListener to or removing one from the collection.

Return to top

Summary

Emits an error message, and a detailed error message to the listener you create when you implement the TraceListener class.

C# Syntax:

public virtual void Fail(    string message,    string detailMessage );

message

A message to emit.

detailMessage

A detailed message to emit.

The default behavior is to display the message and detailed message in a message box when the application is running in a user-interface mode, and to the TraceListener instances in a TraceListenerCollection collection. By default, the TraceListenerCollection collection has an instance of a DefaultTraceListener. You can customize this behavior by adding a TraceListener to or removing one from the collection.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~TraceListener();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

When overridden in a derived class, flushes the output buffer.

C# Syntax:

public virtual void Flush();

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.GetLifetimeService

Summary

Retrieves the current lifetime service object that controls the lifetime policy for this instance.

C# Syntax:

public object GetLifetimeService();

Return Value:

An object of type ILease used to control the lifetime policy for this instance.

For more information about lifetime services, see the LifetimeServices class.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.InitializeLifetimeService

Summary

Obtains a lifetime service object to control the lifetime policy for this instance.

C# Syntax:

public virtual object InitializeLifetimeService();

Return Value:

An object of type ILease used to control the lifetime policy for this instance. This is the current lifetime service object for this instance if one exists; otherwise, a new lifetime service object initialized to the value of the LifetimeServices.LeaseManagerPollTime property.

For more information about lifetime services, see the LifetimeServices class.

The following code example demonstrates creating a lease.

 public class MyClass : MarshalByRefObject
 {
   public override Object InitializeLifetimeService()
   {
     ILease lease = (ILease)base.InitializeLifetimeService();
     if (lease.CurrentState == LeaseState.Initial)
     {
          lease.InitialLeaseTime = TimeSpan.FromMinutes(1);
          lease.SponsorshipTimeout = TimeSpan.FromMinutes(2);
           lease.RenewOnCallTime = TimeSpan.FromSeconds(2);
     }
       return lease;
   }
 }

    

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Writes the value of the object's Object.ToString method to the listener you create when you implement the TraceListener class.

C# Syntax:

public virtual void Write(    object o );

o

An Object whose fully qualified class name you want to write.

Return to top

Summary

When overridden in a derived class, writes the specified message to the listener you create in the derived class.

C# Syntax:

public abstract void Write(    string message );

message

A message to write.

Notes to inheritors: When inheriting from this class, you must implement this method. To support an indentation, you should call TraceListener.WriteIndent if TraceListener.NeedIndent is true. If you need to indent the following line, you must reset TraceListener.NeedIndent to true.

Return to top

Summary

Writes a category name and the value of the object's Object.ToString method to the listener you create when you implement the TraceListener class.

C# Syntax:

public virtual void Write(    object o,    string category );

o

An Object whose fully qualified class name you want to write.

category

A category name used to organize the output.

Return to top

Summary

Writes a category name and a message to the listener you create when you implement the TraceListener class.

C# Syntax:

public virtual void Write(    string message,    string category );

message

A message to write.

category

A category name used to organize the output.

Return to top

Summary

Writes the indent to the listener you create when you implement this class, and resets the TraceListener.NeedIndent property to false.

C# Syntax:

protected virtual void WriteIndent();

Writes the indent and resets TraceListener.NeedIndent to false. Call this method if TraceListener.NeedIndent is true, when you are overloading TraceListener.Write and TraceListener.WriteLine. By default, this method uses blank spaces for indentation.

Return to top

Summary

Writes the value of the object's Object.ToString method to the listener you create when you implement the TraceListener class, followed by a line terminator.

C# Syntax:

public virtual void WriteLine(    object o );

o

An Object whose fully qualified class name you want to write.

The typical line terminator you might implement is a carriage return followed by a line feed (\r\n).

Return to top

Summary

When overridden in a derived class, writes a message to the listener you create in the derived class, followed by a line terminator.

C# Syntax:

public abstract void WriteLine(    string message );

message

A message to write.

The typical line terminator you might implement is a carriage return followed by a line feed (\r\n).

Notes to inheritors: When inheriting from this class, you must implement this method. To support an indentation, call TraceListener.WriteIndent if TraceListener.NeedIndent is true. To indent the following line, you must reset TraceListener.NeedIndent to true.

Return to top

Summary

Writes a category name and the value of the object's Object.ToString method to the listener you create when you implement the TraceListener class, followed by a line terminator.

C# Syntax:

public virtual void WriteLine(    object o,    string category );

o

An Object whose fully qualified class name you want to write.

category

A category name used to organize the output.

The typical line terminator you might implement is a carriage return followed by a line feed (\r\n).

Return to top

Summary

Writes a category name and a message to the listener you create when you implement the TraceListener class, followed by a line terminator.

C# Syntax:

public virtual void WriteLine(    string message,    string category );

message

A message to write.

category

A category name used to organize the output.

The typical line terminator you might implement is a carriage return followed by a line feed (\r\n).

Return to top

Top of page