For examples of how to implement a trace_listener, see the default_trace_listener, text_writer_trace_listener and the event_log_trace_listener classes.

You must enable tracing or debugging to use a trace listener. The syntax is compiler specific. If you use other than cmake to manage your build, refer to the documentation of your build manager.

To enable debugging with cmake, add the add_definitions(-DDEBUG) command line in the CMakeLists.txt of your project, or you can add #define DEBUG to the top of your file but in this case, the compiler options for debug is not activated.
To enable tracing with cmake, add the add_definitions(-DTRACE) command line in the CMakeLists.txt of your project, or you can add #define TRACE to the top of your file.

Note: to Inheritors: Inherit from this class to implement a custom listener for the debug and trace classes. At a minimum, you must implement the write and write_line methods. Additionally, you can implement the fail, close and flush methods.

Public Constructors
	trace_listener ()=default
	Initializes a new instance of the trace_listener class.

	trace_listener (const xtd::string &name)
	Initializes a new instance of the trace_listener class using the specified name as the listener.

Public Properties
uint32	indent_level () const noexcept
	Gets the indent level.

void	indent_level (uint32 indent_level) noexcept
	Sets the indent level.

uint32	indent_size () const noexcept
	Gets the number of spaces in an indent.

void	indent_size (uint32 indent_size) noexcept
	Sets the number of spaces in an indent.

virtual bool	is_thread_safe () const noexcept
	Gets a value indicating whether the trace listener is thread safe.

const xtd::string &	name () const noexcept
	Gets or sets a name for this TraceListener.

void	name (const xtd::string &name) noexcept
	Sets a name for this TraceListener.

trace_options	trace_output_options () const noexcept
	Gets the trace output options.

void	trace_output_options (trace_options trace_output_options) noexcept
	Sets the trace output options.

Public Methods
virtual void	close ()
	When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output.

virtual void	fail (const xtd::string &message)
	Emits an error message to the listener you create when you implement the TraceListener class.

virtual void	fail (const xtd::string &message, const xtd::string &detail_message)
	Emits the specified error message.

virtual void	flush ()
	When overridden in a derived class, flushes the output buffer.

template<typename object >
void	trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, int32 id, const object &data)
	Writes trace information, a data object and event information to the listener specific output.

template<typename object >
void	trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, int32 id, const std::vector< object > &data)
	Writes trace information, a data object and event information to the listener specific output.

template<typename ... objects>
void	trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, int32 id, const objects &... data)
	Writes trace information, an array of data objects and event information to the listener specific output.

virtual void	trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, int32 id)
	Writes trace and event information to the listener specific output.

virtual void	trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, int32 id, const xtd::string &message)
	Writes trace information, a message, and event information to the listener specific output.

template<typename ... objects>
void	trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, int32 id, const xtd::string &format, const objects &... args)
	Writes trace information, a formatted array of objects and event information to the listener specific output.

template<typename activity_id_type >
void	trace_transfer (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, int32 id, const xtd::string &message, const activity_id_type &related_activity_id)
	Writes trace information, a message, a related activity identity and event information to the listener specific output.

template<typename object >
void	write (const object &o)
	Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class.

template<typename object >
void	write (const object &o, const xtd::string &category)
	Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class.

virtual void	write (const xtd::string &message)=0
	Writes the message to the listener you create when you implement the trace_listener class.

template<typename object >
void	write_line (const object &o)
	Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class.

template<typename object >
void	write_line (const object &o, const xtd::string &category)
	Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class.

virtual void	write_line (const xtd::string &message)=0
	Writes the message to the listener you create when you implement the trace_listener class followed by a line terminator.followed by a line terminator.

Protected Properties
bool	need_indent () const noexcept
	Gets a value indicating whether to indent the output.

void	need_indent (bool need_indent) noexcept
	Sets a value indicating whether to indent the output.

void	thread_safe (bool thread_safe) noexcept
	Sets a value indicating whether the trace listener is thread safe.

Protected Methods
virtual void	write_indent ()
	Writes the indent to the listener you create when you implement this class, and resets the NeedIndent property to false.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.

virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.

virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.

virtual type_object	get_type () const noexcept
	Gets the type of the current instance.

template<typename object_t >
xtd::uptr< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.

virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.

Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename object_b_t >
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.

template<typename object_a_t , typename object_b_t >
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Protected Member Functions inherited from xtd::abstract_object
	abstract_object ()=default
	Initializes a new instance of the xtd::abstract_object class.

Constructor & Destructor Documentation

◆ trace_listener() [1/2]

xtd::diagnostics::trace_listener::trace_listener ( )

default

Initializes a new instance of the trace_listener class.

Remarks

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

Property	Default Value
name	The empty string ("").
indent_level	Zero.
indent_size	Four spaces.

◆ trace_listener() [2/2]

xtd::diagnostics::trace_listener::trace_listener ( const xtd::string & name )

explicit

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

Parameters

name	The name of the trace_listener.

Member Function Documentation

◆ indent_level() [1/2]

uint32 xtd::diagnostics::trace_listener::indent_level ( ) const

noexcept

Gets the indent level.

Returns: uint32 The indent level. The default is zero.

Remarks: The IndentLevel property represents the number of times that the indent specified by the IndentSize property is applied. This property is stored on per-thread/per-request basis.

◆ indent_level() [2/2]

void xtd::diagnostics::trace_listener::indent_level ( uint32 indent_level )

noexcept

Sets the indent level.

Parameters

indent_level The indent level. The default is zero.

Remarks: The IndentLevel property represents the number of times that the indent specified by the IndentSize property is applied. This property is stored on per-thread/per-request basis.

◆ indent_size() [1/2]

uint32 xtd::diagnostics::trace_listener::indent_size ( ) const

noexcept

Gets the number of spaces in an indent.

Returns: uint32 The number of spaces in an indent. The default is four spaces.

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

◆ indent_size() [2/2]

void xtd::diagnostics::trace_listener::indent_size ( uint32 indent_size )

noexcept

Sets the number of spaces in an indent.

Parameters

int32 The number of spaces in an indent. The default is four spaces.

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

◆ is_thread_safe()

virtual bool xtd::diagnostics::trace_listener::is_thread_safe ( ) const

virtualnoexcept

Gets a value indicating whether the trace listener is thread safe.

Returns: bool true if the trace listener is thread safe; otherwise, false. The default is false.

Remarks: The value of IsThreadSafe is used to determine whether to use a global lock when writing to the listener. If the value of IsThreadSafe is false, the global lock is used regardless of the value of UseGlobalLock. The global lock is not used only if the value of IsThreadSafe is true and the value of UseGlobalLock is false. The default behavior is to use the global lock whenever writing to the listener.

◆ name() [1/2]

const xtd::string & xtd::diagnostics::trace_listener::name ( ) const

noexcept

Gets or sets a name for this TraceListener.

Returns: string A name for this TraceListener. The default is an empty string ("").

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

◆ name() [2/2]

void xtd::diagnostics::trace_listener::name ( const xtd::string & name )

noexcept

Sets a name for this TraceListener.

Parameters

name	A name for this TraceListener. The default is an empty string ("").

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

◆ trace_output_options() [1/2]

trace_options xtd::diagnostics::trace_listener::trace_output_options ( ) const

noexcept

Gets the trace output options.

Returns: trace_options A bitwise combination of the enumeration values. The default is None.

Remarks

The TraceOutputOptions property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the TraceOutputOptions property for the console trace listener to TraceOptions.Callstack to add call stack information to the trace output.

The TraceOptions enumeration is not used by the following classes and methods:

The EventLogTraceListener class, because it can cause a large volume of data to be written to the log.
The Write and WriteLine methods of the ConsoleTraceListener, DefaultTraceListener, and TextWriterTraceListener classes.
The Write and WriteLine methods of the TraceListener class when they are not overridden in a derived class.

◆ trace_output_options() [2/2]

void xtd::diagnostics::trace_listener::trace_output_options ( trace_options trace_output_options )

noexcept

Sets the trace output options.

Parameters

trace_output_options A bitwise combination of the enumeration values. The default is None.

Remarks

The TraceOutputOptions property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the TraceOutputOptions property for the console trace listener to TraceOptions.Callstack to add call stack information to the trace output.

The TraceOptions enumeration is not used by the following classes and methods:

The EventLogTraceListener class, because it can cause a large volume of data to be written to the log.
The Write and WriteLine methods of the ConsoleTraceListener, DefaultTraceListener, and TextWriterTraceListener classes.
The Write and WriteLine methods of the TraceListener class when they are not overridden in a derived class.

◆ close()

virtual void xtd::diagnostics::trace_listener::close ( )

virtual

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

Remarks: 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.

Reimplemented in xtd::diagnostics::default_trace_listener, xtd::diagnostics::ostream_trace_listener, and xtd::forms::control_trace_listener.

◆ fail() [1/2]

virtual void xtd::diagnostics::trace_listener::fail ( const xtd::string & message )

inlinevirtual

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

Parameters

message A message to emit.

Remarks: 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.

◆ fail() [2/2]

virtual void xtd::diagnostics::trace_listener::fail	(	const xtd::string &	message,
		const xtd::string &	detail_message
	)

inlinevirtual

Emits the specified error message.

Parameters

message	A message to emit.
detailMessage	A detailed message to emit.

Remarks: 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.

◆ flush()

virtual void xtd::diagnostics::trace_listener::flush ( )

inlinevirtual

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

Reimplemented in xtd::diagnostics::default_trace_listener, xtd::diagnostics::ostream_trace_listener, and xtd::forms::control_trace_listener.

◆ trace_data() [1/3]

template<typename object >

void xtd::diagnostics::trace_listener::trace_data	(	const xtd::diagnostics::trace_event_cache &	event_cache,
		const xtd::string &	source,
		const xtd::diagnostics::trace_event_type &	event_type,
		int32	id,
		const object &	data
	)

inline

Writes trace information, a data object and event information to the listener specific output.

Parameters

event_cache	A trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
source	A name used to identify the output, typically the name of the application that generated the trace event.
eventType	One of the TraceEventType values specifying the type of event that has caused the trace.
id	A numeric identifier for the event.
data	The trace data to emit.

Remarks: Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.; The default implementation writes the event_cache, source, eventType and id parameters in the header and footer of the trace. The data parameter is written as the body of the trace message. The ToString method of the data object is used to convert the object to a String.

◆ trace_data() [2/3]

template<typename object >

void xtd::diagnostics::trace_listener::trace_data	(	const xtd::diagnostics::trace_event_cache &	event_cache,
		const xtd::string &	source,
		const xtd::diagnostics::trace_event_type &	event_type,
		int32	id,
		const std::vector< object > &	data
	)

inline

Writes trace information, a data object and event information to the listener specific output.

Parameters

event_cache	A trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
source	A name used to identify the output, typically the name of the application that generated the trace event.
eventType	One of the TraceEventType values specifying the type of event that has caused the trace.
id	A numeric identifier for the event.
data	The trace data to emit.

Remarks: Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.; The default implementation writes the event_cache, source, eventType and id parameters in the header and footer of the trace. The data parameter is written as the body of the trace message. The ToString method of the data object is used to convert the object to a String.

◆ trace_data() [3/3]

template<typename ... objects>

void xtd::diagnostics::trace_listener::trace_data	(	const xtd::diagnostics::trace_event_cache &	event_cache,
		const xtd::string &	source,
		const xtd::diagnostics::trace_event_type &	event_type,
		int32	id,
		const objects &...	data
	)

inline

Writes trace information, an array of data objects and event information to the listener specific output.

Parameters

event_cache	A trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
source	A name used to identify the output, typically the name of the application that generated the trace event.
eventType	One of the TraceEventType values specifying the type of event that has caused the trace.
id	A numeric identifier for the event.
data	An array of objects to emit as data.

Remarks: Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.; The default implementation writes the event_cache, source, eventType and id parameters in the header and footer of the trace. The data parameter is written as the body of the trace message. The ToString method of the data object is used to convert the object to a String.

◆ trace_event() [1/3]

virtual void xtd::diagnostics::trace_listener::trace_event	(	const xtd::diagnostics::trace_event_cache &	event_cache,
		const xtd::string &	source,
		const xtd::diagnostics::trace_event_type &	event_type,
		int32	id
	)

inlinevirtual

Writes trace and event information to the listener specific output.

Parameters

event_cache	A trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
source	A name used to identify the output, typically the name of the application that generated the trace event.
eventType	One of the TraceEventType values specifying the type of event that has caused the trace.
id	A numeric identifier for the event.

Remarks: Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.; The default implementation writes the values of the source, eventType and id parameters as a header. The event_cache data is written as a footer, the nature of the output data being dependent on the value of the TraceOutputOptions property.

◆ trace_event() [2/3]

virtual void xtd::diagnostics::trace_listener::trace_event	(	const xtd::diagnostics::trace_event_cache &	event_cache,
		const xtd::string &	source,
		const xtd::diagnostics::trace_event_type &	event_type,
		int32	id,
		const xtd::string &	message
	)

inlinevirtual

Writes trace information, a message, and event information to the listener specific output.

Parameters

event_cache	A trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
source	A name used to identify the output, typically the name of the application that generated the trace event.
eventType	One of the TraceEventType values specifying the type of event that has caused the trace.
id	A numeric identifier for the event.
message	A message to write.

Remarks: Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.; The default implementation writes the values of the source, eventType and id parameters as a header. The event_cache data is written as a footer, the nature of the output data being dependent on the value of the TraceOutputOptions property.

◆ trace_event() [3/3]

template<typename ... objects>

void xtd::diagnostics::trace_listener::trace_event	(	const xtd::diagnostics::trace_event_cache &	event_cache,
		const xtd::string &	source,
		const xtd::diagnostics::trace_event_type &	event_type,
		int32	id,
		const xtd::string &	format,
		const objects &...	args
	)

inline

Writes trace information, a formatted array of objects and event information to the listener specific output.

Parameters

event_cache	A trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
source	A name used to identify the output, typically the name of the application that generated the trace event.
eventType	One of the TraceEventType values specifying the type of event that has caused the trace.
id	A numeric identifier for the event.
format	A format string that contains zero or more format items, which correspond to objects in the args array.
args	An object array containing zero or more objects to format.

Remarks: Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.; The default implementation writes the values of the source, eventType and id parameters as a header. The args object array is converted to a string using the Format method, passing the format string and args array to format the string as the message portion of the trace. The event_cache data is written as a footer, the nature of the output data being dependent on the value of the TraceOutputOptions property.

◆ trace_transfer()

template<typename activity_id_type >

void xtd::diagnostics::trace_listener::trace_transfer	(	const xtd::diagnostics::trace_event_cache &	event_cache,
		const xtd::string &	source,
		int32	id,
		const xtd::string &	message,
		const activity_id_type &	related_activity_id
	)

inline

Writes trace information, a message, a related activity identity and event information to the listener specific output.

Parameters

event_cache	A trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
source	A name used to identify the output, typically the name of the application that generated the trace event.
id	A numeric identifier for the event.
message	A message to write.
relatedActivityId	A Guid object identifying a related activity.

Remarks: Important This method is not intended to be called directly by application code but by members of the Debug, Trace, and TraceSource classes to write trace data to output.; The TraceTransfer method is used for the correlation of related traces. The TraceTransfer method calls the TraceEvent method to process the call, with the eventType level set to Transfer and the relatedActivityIdGuid as a string appended to the message.; activity_id_type is generally a guid.

◆ write() [1/3]

template<typename object >

void xtd::diagnostics::trace_listener::write ( const object & o )

inline

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

Parameters

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

◆ write() [2/3]

template<typename object >

void xtd::diagnostics::trace_listener::write	(	const object &	o,
		const xtd::string &	category
	)

inline

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

Parameters

o	An Object whose fully qualified class name you want to write.
category	A category name used to organize the output.

◆ write() [3/3]

virtual void xtd::diagnostics::trace_listener::write ( const xtd::string & message )

pure virtual

Writes the message to the listener you create when you implement the trace_listener class.

Parameters

message A string you want to write.

Implemented in xtd::diagnostics::default_trace_listener, xtd::diagnostics::ostream_trace_listener, and xtd::forms::control_trace_listener.

◆ write_line() [1/3]

template<typename object >

void xtd::diagnostics::trace_listener::write_line ( const object & o )

inline

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

Parameters

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

◆ write_line() [2/3]

template<typename object >

void xtd::diagnostics::trace_listener::write_line	(	const object &	o,
		const xtd::string &	category
	)

inline

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

Parameters

o	An Object whose fully qualified class name you want to write.
category	A category name used to organize the output.

◆ write_line() [3/3]

virtual void xtd::diagnostics::trace_listener::write_line ( const xtd::string & message )

pure virtual

Writes the message to the listener you create when you implement the trace_listener class followed by a line terminator.followed by a line terminator.

Parameters

message A string you want to write.

Implemented in xtd::diagnostics::default_trace_listener, xtd::diagnostics::ostream_trace_listener, and xtd::forms::control_trace_listener.

◆ need_indent() [1/2]

bool xtd::diagnostics::trace_listener::need_indent ( ) const

protectednoexcept

Gets a value indicating whether to indent the output.

Returns: true if the output should be indented; otherwise, false.

◆ need_indent() [2/2]

void xtd::diagnostics::trace_listener::need_indent ( bool need_indent )

protectednoexcept

Sets a value indicating whether to indent the output.

Parameters

need_indent true if the output should be indented; otherwise, false.

◆ thread_safe()

void xtd::diagnostics::trace_listener::thread_safe ( bool thread_safe )

protectednoexcept

Sets a value indicating whether the trace listener is thread safe.

Parameters

thread_safe true if the trace listener is thread safe; otherwise, false. The default is false.

◆ write_indent()

virtual void xtd::diagnostics::trace_listener::write_indent ( )

inlineprotectedvirtual

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

Remarks: This method writes the indent and resets the NeedIndent property to false. Call this method if NeedIndent is true when you are overriding the Write and WriteLine methods. By default, this method uses blank spaces for indentation. The size of the indent is determined by the values of the IndentSize and IndentLevel properties. The IndentLevel property represents the number of times the indent of the size specified by the IndentSize property is applied. This method is called by the DefaultTraceListener and TextWriterTraceListener classes.

The documentation for this class was generated from the following file:

xtd.core/include/xtd/diagnostics/trace_listener.h

Definition

Public Constructors

Public Properties

Public Methods

Protected Properties

Protected Methods

Additional Inherited Members

Constructor & Destructor Documentation

◆ trace_listener() [1/2]

◆ trace_listener() [2/2]

Member Function Documentation

◆ indent_level() [1/2]

◆ indent_level() [2/2]

◆ indent_size() [1/2]

◆ indent_size() [2/2]

◆ is_thread_safe()

◆ name() [1/2]

◆ name() [2/2]

◆ trace_output_options() [1/2]

◆ trace_output_options() [2/2]

◆ close()

◆ fail() [1/2]

◆ fail() [2/2]

◆ flush()

◆ trace_data() [1/3]

◆ trace_data() [2/3]

◆ trace_data() [3/3]

◆ trace_event() [1/3]

◆ trace_event() [2/3]

◆ trace_event() [3/3]

◆ trace_transfer()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

◆ write_line() [1/3]

◆ write_line() [2/3]

◆ write_line() [3/3]

◆ need_indent() [1/2]

◆ need_indent() [2/2]

◆ thread_safe()

◆ write_indent()