xtd 0.2.0
Loading...
Searching...
No Matches
xtd::diagnostics::trace_listener Class Referenceabstract
Inheritance diagram for xtd::diagnostics::trace_listener:
xtd::abstract_object xtd::object xtd::diagnostics::default_trace_listener xtd::diagnostics::ostream_trace_listener xtd::forms::control_trace_listener xtd::diagnostics::console_trace_listener

Definition

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

trace_listener()=default
Initializes a new instance of the trace_listener class.
#define core_export_
Define shared library export.
Definition core_export.hpp:13
Inheritance
xtd::abstract_objectxtd::abstract_objectxtd::diagnostics::trace_listener
Header
#include <xtd/diagnostics/trace_listener>
Namespace
xtd::diagnostics
Library
xtd.core
Remarks
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.
To disable debug mode with CMake, add the command line add_definitions(-DNDEBUG) in your CMakeLists.txt, or define NDEBUG at the top of your file.
Note
If you define #define DEBUG above your includes, debug mode will still be active even if NDEBUG is defined.
Remarks
To activate your code if DEBUG is defined, you must enclose calls to the methods of Debug in an #if DEBUG ... #endif block.
To disable trace mode with CMake, add the command line add_definitions(-DNTRACE) in your CMakeLists.txt, or define NTRACE at the top of your file.
Note
If you define #define TRACE above your includes, trace mode will still be active even if NTRACE is defined.
Remarks
To activate your code if TRACE is defined, you must enclose calls to the methods of Debug in an #if TRACE ... #endif block.
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 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

auto indent_level () const noexcept -> xtd::uint32
 Gets the indent level.
auto indent_level (xtd::uint32 indent_level) noexcept -> void
 Sets the indent level.
auto indent_size () const noexcept -> xtd::uint32
 Gets the number of spaces in an indent.
auto indent_size (xtd::uint32 indent_size) noexcept -> void
 Sets the number of spaces in an indent.
virtual auto is_thread_safe () const noexcept -> bool
 Gets a value indicating whether the trace listener is thread safe.
auto name () const noexcept -> const xtd::string &
 Gets or sets a name for this TraceListener.
auto name (const xtd::string &name) noexcept -> void
 Sets a name for this TraceListener.
auto trace_output_options () const noexcept -> xtd::diagnostics::trace_options
 Gets the trace output options.
auto trace_output_options (xtd::diagnostics::trace_options trace_output_options) noexcept -> void
 Sets the trace output options.

Public Methods

virtual auto close () -> void
 When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output.
virtual auto fail (const xtd::string &message) -> void
 Emits an error message to the listener you create when you implement the TraceListener class.
virtual auto fail (const xtd::string &message, const xtd::string &detail_message) -> void
 Emits the specified error message.
virtual auto flush () -> void
 When overridden in a derived class, flushes the output buffer.
template<typename object_t>
auto trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, xtd::int32 id, const object_t &data) -> void
 Writes trace information, a data object and event information to the listener specific output.
template<typename object_t>
auto trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, xtd::int32 id, const xtd::array< object_t > &data) -> void
 Writes trace information, a data object and event information to the listener specific output.
template<typename ... objects_t>
auto trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, xtd::int32 id, objects_t &&... data) -> void
 Writes trace information, an array of data objects and event information to the listener specific output.
virtual auto trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, xtd::int32 id) -> void
 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_t>
auto trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, const xtd::diagnostics::trace_event_type &event_type, xtd::int32 id, const xtd::string &format, const objects_t &... args) -> void
 Writes trace information, a formatted array of objects and event information to the listener specific output.
template<typename guid_t>
auto trace_transfer (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::string &source, xtd::int32 id, const xtd::string &message, const guid_t &related_activity_id) -> void
 Writes trace information, a message, a related activity identity and event information to the listener specific output.
template<typename object_t>
auto write (const object_t &o) -> void
 Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class.
template<typename object_t>
auto write (const object_t &o, const xtd::string &category) -> void
 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_t>
auto write_line (const object_t &o) -> void
 Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class.
template<typename object_t>
auto write_line (const object_t &o, const xtd::string &category) -> void
 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 auto write_line (const xtd::string &message) -> void=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

auto need_indent () const noexcept -> bool
 Gets a value indicating whether to indent the output.
auto need_indent (bool need_indent) noexcept -> void
 Sets a value indicating whether to indent the output.
auto thread_safe (bool thread_safe) noexcept -> void
 Sets a value indicating whether the trace listener is thread safe.

Protected Methods

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

Additional Inherited Members

 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 xtd::size 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::unique_ptr_object< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
virtual xtd::string to_string () const
 Returns a xtd::string that represents the current 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.
 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
nameThe name of the trace_listener.

Member Function Documentation

◆ indent_level() [1/2]

auto xtd::diagnostics::trace_listener::indent_level ( ) const -> xtd::uint32
nodiscardnoexcept

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]

auto xtd::diagnostics::trace_listener::indent_level ( xtd::uint32 indent_level) -> void
noexcept

Sets the indent level.

Parameters
indent_levelThe 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]

auto xtd::diagnostics::trace_listener::indent_size ( ) const -> xtd::uint32
nodiscardnoexcept

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]

auto xtd::diagnostics::trace_listener::indent_size ( xtd::uint32 indent_size) -> void
noexcept

Sets the number of spaces in an indent.

Parameters
int32The 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 auto xtd::diagnostics::trace_listener::is_thread_safe ( ) const -> bool
nodiscardvirtualnoexcept

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]

auto xtd::diagnostics::trace_listener::name ( ) const -> const xtd::string &
nodiscardnoexcept

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]

auto xtd::diagnostics::trace_listener::name ( const xtd::string & name) -> void
noexcept

Sets a name for this TraceListener.

Parameters
nameA 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]

auto xtd::diagnostics::trace_listener::trace_output_options ( ) const -> xtd::diagnostics::trace_options
nodiscardnoexcept

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]

auto xtd::diagnostics::trace_listener::trace_output_options ( xtd::diagnostics::trace_options trace_output_options) -> void
noexcept

Sets the trace output options.

Parameters
trace_output_optionsA 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 auto xtd::diagnostics::trace_listener::close ( ) -> void
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 auto xtd::diagnostics::trace_listener::fail ( const xtd::string & message) -> void
inlinevirtual

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

Parameters
messageA 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 auto xtd::diagnostics::trace_listener::fail ( const xtd::string & message,
const xtd::string & detail_message ) -> void
inlinevirtual

Emits the specified error message.

Parameters
messageA message to emit.
detail_messageA 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 auto xtd::diagnostics::trace_listener::flush ( ) -> void
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_t>
auto 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,
xtd::int32 id,
const object_t & data ) -> void
inline

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

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
event_typeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
dataThe 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_t>
auto 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,
xtd::int32 id,
const xtd::array< object_t > & data ) -> void
inline

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

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
event_typeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
dataThe 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_t>
auto 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,
xtd::int32 id,
objects_t &&... data ) -> void
inline

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

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
dataAn 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 auto 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,
xtd::int32 id ) -> void
inlinevirtual

Writes trace and event information to the listener specific output.

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA 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_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
messageA 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_t>
auto 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,
xtd::int32 id,
const xtd::string & format,
const objects_t &... args ) -> void
inline

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

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
eventTypeOne of the TraceEventType values specifying the type of event that has caused the trace.
idA numeric identifier for the event.
formatA format string that contains zero or more format items, which correspond to objects in the args array.
argsAn 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 guid_t>
auto xtd::diagnostics::trace_listener::trace_transfer ( const xtd::diagnostics::trace_event_cache & event_cache,
const xtd::string & source,
xtd::int32 id,
const xtd::string & message,
const guid_t & related_activity_id ) -> void
inline

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

Parameters
event_cacheA trace_event_cache object that contains the current process ID, thread ID, and stack trace information.
sourceA name used to identify the output, typically the name of the application that generated the trace event.
idA numeric identifier for the event.
messageA message to write.
relatedActivityIdA 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_t>
auto xtd::diagnostics::trace_listener::write ( const object_t & o) -> void
inline

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

Parameters
oAn Object whose fully qualified class name you want to write.

◆ write() [2/3]

template<typename object_t>
auto xtd::diagnostics::trace_listener::write ( const object_t & o,
const xtd::string & category ) -> void
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
oAn Object whose fully qualified class name you want to write.
categoryA 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
messageA 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_t>
auto xtd::diagnostics::trace_listener::write_line ( const object_t & o) -> void
inline

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

Parameters
oAn Object whose fully qualified class name you want to write.

◆ write_line() [2/3]

template<typename object_t>
auto xtd::diagnostics::trace_listener::write_line ( const object_t & o,
const xtd::string & category ) -> void
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
oAn Object whose fully qualified class name you want to write.
categoryA category name used to organize the output.

◆ write_line() [3/3]

virtual auto xtd::diagnostics::trace_listener::write_line ( const xtd::string & message) -> void
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
messageA 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]

auto xtd::diagnostics::trace_listener::need_indent ( ) const -> bool
nodiscardprotectednoexcept

Gets a value indicating whether to indent the output.

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

◆ need_indent() [2/2]

auto xtd::diagnostics::trace_listener::need_indent ( bool need_indent) -> void
protectednoexcept

Sets a value indicating whether to indent the output.

Parameters
need_indenttrue if the output should be indented; otherwise, false.

◆ thread_safe()

auto xtd::diagnostics::trace_listener::thread_safe ( bool thread_safe) -> void
protectednoexcept

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

Parameters
thread_safetrue if the trace listener is thread safe; otherwise, false. The default is false.

◆ write_indent()

virtual auto xtd::diagnostics::trace_listener::write_indent ( ) -> void
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: