xtd::diagnostics::trace_source Class Reference

Inheritance diagram for xtd::diagnostics::trace_source:

Definition

Provides a set of methods and properties that enable applications to trace the execution of code and associate trace messages with their source.

class core_export_ trace_source : public xtd::object

Inheritance

xtd::object → xtd::diagnostics::trace_source

Header

#include <xtd/diagnostics/trace_source>

Namespace

xtd::diagnostics

Library

xtd.core

Remarks

The trace_source class is used by applications to produce traces that can be associated with the application. trace_source provides tracing methods that allow you to easily trace events, trace data, and issue informational traces.

The trace_source 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.

trace_source 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 can customize the tracing output's target by adding or removing trace_listener instances to or from the collection stored in the trace_source::listeners property. By default, trace output is produced using an instance of the default_trace_listener class.

Note

Adding a trace listener to the listeners 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 trace_source methods in try/catch blocks to detect and handle any exceptions from trace listeners.

Remarks

The source_switch class provides the means to dynamically control the tracing output. You can modify the value of the source switch without recompiling your application.

The trace_event_type enumeration is used to define the event type of the trace message. Trace filters use the trace_event_type 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 should_trace method on that filter to determine whether or not to produce the trace information.

The trace listeners use the values of the trace class properties indent, indent_size, and auto_flush to format trace output.

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.

Public Constructors
	trace_source (const xtd::string &name)
	Initializes a new instance of the Trace_Source class, using the specified name for the source.
	trace_source (const xtd::string &name, xtd::diagnostics::source_levels default_levels)
	Initializes a new instance of the Trace_Source class, using the specified name for the source.

Public Properties
xtd::diagnostics::trace_listener_collection &	listeners () noexcept
	Gets the collection of trace listeners for the trace source.
void	listeners (const xtd::diagnostics::trace_listener_collection &listeners) noexcept
	Sets the collection of trace listeners for the trace source.
const xtd::string &	name () const noexcept
	Gets the name of the trace source.
const xtd::diagnostics::source_switch &	source_switch () const noexcept
	Gets the source switch value.
void	source_switch (const xtd::diagnostics::source_switch &source_switch) noexcept
	Sets the source switch value.

Public Methods
void	close ()
	Closes all the trace listeners in the trace listener collection.
void	flush ()
	Flushes all the trace listeners in the trace listener collection.
template<class object_t>
void	trace_data (const xtd::diagnostics::trace_event_type &event_type, int32 id, const object_t &data)
	Writes trace data to the trace listeners in the Listeners collection using the specified event type, event identifier, and trace data.
template<class object_t>
void	trace_data (const xtd::diagnostics::trace_event_type &event_type, int32 id, const xtd::array< object_t > &data)
	Writes trace data to the trace listeners in the Listeners collection using the specified event type, event identifier, and trace data.
void	trace_event (const xtd::diagnostics::trace_event_type &event_type, int32 id)
	Writes a trace event message to the trace listeners in the listeners collection using the specified event type and event identifier.
void	trace_event (const xtd::diagnostics::trace_event_type &event_type, int32 id, const xtd::string &message)
	Writes a trace event message to the trace listeners in the listeners collection using the specified event type, event identifier adn message.
template<class ... objects>
void	trace_event (const xtd::diagnostics::trace_event_type &event_type, int32 id, const xtd::string &format, const objects &... args)
	Writes a trace event message to the trace listeners in the listeners collection using the specified event type, event identifier, and argument array and format.
void	trace_information (const xtd::string &message)
	Writes an informational message to the trace listeners in the listeners collection using the specified message.
template<class ... objects_t>
void	trace_information (const xtd::string &format, const objects_t &... args)
	Writes an informational message to the trace listeners in the listeners collection using the specified object array and formatting information.
template<class guid_t>
void	trace_transfer (int32 id, const xtd::string &message, const guid_t &related_activity_id)
	Writes a trace transfer message to the trace listeners in the listeners collection using the specified numeric identifier, message, and related activity identifier.

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<class 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 noexcept
	Returns a xtd::string that represents the current object.
template<class object_a_t, class 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<class object_a_t, class 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.

Constructor & Destructor Documentation

trace_source() [1/2]

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

explicit

Initializes a new instance of the Trace_Source class, using the specified name for the source.

Parameters

name	The name of the source (typically, the name of the application).

trace_source() [2/2]

xtd::diagnostics::trace_source::trace_source ( const xtd::string & name, xtd::diagnostics::source_levels default_levels )

explicit

Initializes a new instance of the Trace_Source class, using the specified name for the source.

Parameters

name	The name of the source (typically, the name of the application).
default_level	A bitwise combination of the enumeration values that specifies the default source level at which to trace

Member Function Documentation

listeners() [1/2]

xtd::diagnostics::trace_listener_collection & xtd::diagnostics::trace_source::listeners ( )

noexcept

Gets the collection of trace listeners for the trace source.

Returns

A trace_listener_collection that contains the active trace listeners associated with the source.

Remarks

Use this property to access and perform operations on the trace listeners.

listeners() [2/2]

void xtd::diagnostics::trace_source::listeners ( const xtd::diagnostics::trace_listener_collection & listeners )

noexcept

Sets the collection of trace listeners for the trace source.

Parameters

listeners

A trace_listener_collection that contains the active trace listeners associated with the source.

Remarks

Use this property to access and perform operations on the trace listeners.

name()

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

noexcept

Gets the name of the trace source.

Returns

The name of the trace source.

source_switch() [1/2]

const xtd::diagnostics::source_switch & xtd::diagnostics::trace_source::source_switch ( ) const

noexcept

Gets the source switch value.

Returns

A SourceSwitch object representing the source switch value.

Remarks

The source_switch 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 should_trace method of the source_switch to determine whether to proceed with the trace. If the call returns true, the listeners are called.

source_switch() [2/2]

void xtd::diagnostics::trace_source::source_switch ( const xtd::diagnostics::source_switch & source_switch )

noexcept

Sets the source switch value.

Parameters

source_switch

A SourceSwitch object representing the source switch value.

Remarks

The source_switch 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 should_trace method of the source_switch to determine whether to proceed with the trace. If the call returns true, the listeners are called.

close()

void xtd::diagnostics::trace_source::close

(

)

Closes all the trace listeners in the trace listener collection.

Remarks

The close method calls the close method of each trace listener in the listeners collection.

flush()

void xtd::diagnostics::trace_source::flush

(

)

Flushes all the trace listeners in the trace listener collection.

Remarks

The flush method calls the flush method of each trace listener in the listeners collection.

trace_data() [1/2]

template<class object_t>

void xtd::diagnostics::trace_source::trace_data ( const xtd::diagnostics::trace_event_type & event_type, int32 id, const object_t & data )

inline

Writes trace data to the trace listeners in the Listeners collection using the specified event type, event identifier, and trace data.

Parameters

event_type	One of the enumeration values that specifies the event type of the trace data.
id	A numeric identifier for the event.
data	The trace data.

Remarks

The trace_data method, like the trace_event 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 trace_data method calls the source_switch::should_trace method of the source_switch object returned by the source_switch property. If should_trace returns true, trace_data calls the corresponding trace_data method on all listeners. Otherwise, trace_data returns without calling the listeners' methods.

trace_data() [2/2]

template<class object_t>

void xtd::diagnostics::trace_source::trace_data ( const xtd::diagnostics::trace_event_type & event_type, int32 id, const xtd::array< object_t > & data )

inline

Writes trace data to the trace listeners in the Listeners collection using the specified event type, event identifier, and trace data.

Parameters

event_type	One of the enumeration values that specifies the event type of the trace data.
id	A numeric identifier for the event.
data	The trace data.

Remarks

The trace_data method, like the trace_event 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 trace_data method calls the source_switch::should_trace method of the source_switch object returned by the source_switch property. If should_trace returns true, trace_data calls the corresponding trace_data method on all listeners. Otherwise, trace_data returns without calling the listeners' methods.

trace_event() [1/3]

void xtd::diagnostics::trace_source::trace_event ( const xtd::diagnostics::trace_event_type & event_type, int32 id )

inline

Writes a trace event message to the trace listeners in the listeners collection using the specified event type and event identifier.

Parameters

event_type	One of the enumeration values that specifies the event type of the trace data.
id	A numeric identifier for the event.

Remarks

The trace_event 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.

trace_event() [2/3]

void xtd::diagnostics::trace_source::trace_event ( const xtd::diagnostics::trace_event_type & event_type, int32 id, const xtd::string & message )

inline

Writes a trace event message to the trace listeners in the listeners collection using the specified event type, event identifier adn message.

Parameters

event_type	One of the enumeration values that specifies the event type of the trace data.
id	A numeric identifier for the event.
message	The trace message to write.

trace_event() [3/3]

template<class ... objects>

void xtd::diagnostics::trace_source::trace_event ( const xtd::diagnostics::trace_event_type & event_type, int32 id, const xtd::string & format, const objects &... args )

inline

Writes a trace event message to the trace listeners in the listeners collection using the specified event type, event identifier, and argument array and format.

Parameters

event_type	One of the enumeration values that specifies the event type of the trace data.
id	A numeric identifier for the event.
format	A composite format string that contains text intermixed with zero or more format items, which correspond to objects in the args array.
args...	An object array containing zero or more objects to format.

trace_information() [1/2]

void xtd::diagnostics::trace_source::trace_information

(

const xtd::string &

message

)

Writes an informational message to the trace listeners in the listeners collection using the specified message.

Parameters

message

The informative message to write.

Remarks

The trace_information method provides an informational message intended to be read by users and not by tools.

trace_information(const std::string&, calls the trace_event(const trace_eventType&, std::int32_t, const xtd::string&, ...objects_t) method, setting event_type to trace_event_type.Information and passing the message content as an object array with formatting information. The trace_event(const trace_event_type, std::int32_t, xtd::string&) method in turn calls the trace_event(const trace_event_cache&, const xtd::string&, trace_event_type, std::int32_t, const xtd::string&) method of each trace listener.

trace_information() [2/2]

template<class ... objects_t>

void xtd::diagnostics::trace_source::trace_information ( const xtd::string & format, const objects_t &... args )

inline

Writes an informational message to the trace listeners in the listeners collection using the specified object array and formatting information.

Parameters

format	A composite format string that contains text intermixed with zero or more format items, which correspond to objects in the args array.
args...	An array containing zero or more objects to format.

Remarks

The trace_information method provides an informational message intended to be read by users and not by tools.

trace_information(const std::string&, const Objects_t) calls the trace_event(const trace_eventType&, std::int32_t, const xtd::string&, ...objects_t) method, setting event_type to trace_event_type.Information and passing the message content as an object array with formatting information. The trace_event(const trace_event_type, std::int32_t, xtd::string&, ...objects_t) method in turn calls the trace_event(const trace_event_cache&, const xtd::string&, trace_event_type, std::int32_t, const xtd::string&, ...objects_t) method of each trace listener.

trace_transfer()

template<class guid_t>

void xtd::diagnostics::trace_source::trace_transfer ( int32 id, const xtd::string & message, const guid_t & related_activity_id )

inline

Writes a trace transfer message to the trace listeners in the listeners collection using the specified numeric identifier, message, and related activity identifier.

Parameters

id	A numeric identifier for the event.
message	The trace message to write.
related_activity_id	A structure that identifies the related activity.

Remarks

The trace_transfer method calls the trace_transfer method of each trace listener in the listeners property to write the trace information. The default trace_transfer method in the base trace_listener class calls the trace_listener::trace_event(const trace_event_cache&, const xtd::string&, trace_event_type, std::int32_t, const xtd::string&) method to process the call, setting event_type to trace_event_type::transfer and appending a string representation of the related_activity_id GUID to message.

trace_transfer is intended to be used with the logical operations of a correlation_manager. The related_activity_id parameter relates to the activity_id property of a correlation_manager object. If a logical operation begins in one activity and transfers to another, the second activity logs the transfer by calling the trace_transfer method. The trace_transfer 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.

---

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

• xtd.core/include/xtd/diagnostics/trace_source.hpp