Logging​Channel Logging​Channel Logging​Channel Class

Definition

Represents a source of log messages.

public : sealed class LoggingChannel : ILoggingChannel, ILoggingChannel2, ILoggingTarget, IClosablepublic sealed class LoggingChannel : ILoggingChannel, ILoggingChannel2, ILoggingTarget, IDisposablePublic NotInheritable Class LoggingChannel Implements ILoggingChannel, ILoggingChannel2, ILoggingTarget, IDisposable
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The default LoggingLevel is Verbose.

Add LoggingChannel instances to a LoggingSession or a FileLoggingSession to enable logging in your app.

Windows 10 Two modes of operation are now supported: Windows 8.1 compatibility mode and the new behavior supported by Windows 10 and later which allows you to log self-describing Event Tracing for Windows (ETW) events without a manifest. + For Windows 8.1 compatibility mode, create the object using the LoggingChannel(String) constructor.

  • For Windows 10 and later specific behavior, create the object using the LoggingChannel(String, LoggingChannelOptions) or LoggingChannel(String, LoggingChannelOptions, Guid) constructor. The differences between these two modes are:
Windows 8.1 compatibility modeWindows 10 and later specific behavior
Some LoggingChannel events may reference the 4bd2826e-54a1-4ba9-bf63-92b73ea1ac4a which is the GUID for the Microsoft-Windows-Diagnostics-LoggingChannel manifest that is available on Windows 8.1 or later.All events are self-describing. No manifest is required.
The Id property is always 4bd2826e-54a1-4ba9-bf63-92b73ea1ac4a, which is the GUID for the Microsoft-Windows-Diagnostics-LoggingChannel manifest.The Id property varies based on how the channel is constructed. If the LoggingChannel(String, LoggingChannelOptions) constructor is used, the Id is determined by hashing the name parameter. If the LoggingChannel(String, LoggingChannelOptions, Guid) constructor is used, the specified id parameter is used.
Events generated by the LogMessage, LogValuePair, the LoggingActivity constructors or destructor, or activity.Activity.Close method use manifest-based event encoding. All other events use self-describing TraceLogging event encoding.All events use self-describing TraceLogging event encoding.
The channel provider name is Microsoft-Windows-Diagnostics-LoggingChannel. The channel name is recorded in each event in the payload field LoggingChannelName.The channel name is used as the provider name. Events will not have a LoggingChannelName field.

Constructors

LoggingChannel(String) LoggingChannel(String) LoggingChannel(String)

This constructor creates a LoggingChannel in Windows 8.1 compatibility mode.

public : LoggingChannel(PlatForm::String name)public LoggingChannel(String name)Public Sub New(name As String)
Parameters
name
PlatForm::String String String

The name of the logging channel.

Attributes

Remarks

This constructor creates a LoggingChannel in Windows 8.1 compatibility mode. For a description of the differences between Windows 8.1 compatibility mode and the new behavior supported by Windows 10, see LoggingChannel.

Windows 10 This constructor should only be used if you need compatibility with Windows 8.1. For Windows 10 and later, use LoggingChannel(String, LoggingChannelOptions) or LoggingChannel(String, LoggingChannelOptions, Guid).

See Also

LoggingChannel(String, LoggingChannelOptions) LoggingChannel(String, LoggingChannelOptions) LoggingChannel(String, LoggingChannelOptions)

Initializes a new instance of the LoggingChannel class with the specified options.

public : LoggingChannel(PlatForm::String name, LoggingChannelOptions options)public LoggingChannel(String name, LoggingChannelOptions options)Public Sub New(name As String, options As LoggingChannelOptions)
Parameters
name
PlatForm::String String String

The name of the logging channel.

options
LoggingChannelOptions LoggingChannelOptions LoggingChannelOptions

The channel options. Pass null to specify the default options.

Attributes
See Also

LoggingChannel(String, LoggingChannelOptions, Guid) LoggingChannel(String, LoggingChannelOptions, Guid) LoggingChannel(String, LoggingChannelOptions, Guid)

Initializes a new instance of the LoggingChannel class with the specified options and channel ID.

public : LoggingChannel(PlatForm::String name, LoggingChannelOptions options, PlatForm::Guid id)public LoggingChannel(String name, LoggingChannelOptions options, Guid id)Public Sub New(name As String, options As LoggingChannelOptions, id As Guid)
Parameters
name
PlatForm::String String String

The name of the logging channel.

options
LoggingChannelOptions LoggingChannelOptions LoggingChannelOptions

The channel options. Pass null to specify the default options.

id
PlatForm::Guid Guid Guid

The channel identifier to use instead of the automatically generated identifier.

Attributes
See Also

Properties

Enabled Enabled Enabled

Gets a value that indicates whether at least one session is logging events from this channel.

public : PlatForm::Boolean Enabled { get; }public bool Enabled { get; }Public ReadOnly Property Enabled As bool
Value
PlatForm::Boolean bool bool

Returns true if at least one session is listening for events from the channel, and otherwise false.

Attributes

Id Id Id

Returns the provider identifier for this channel.

public : PlatForm::Guid Id { get; }public Guid Id { get; }Public ReadOnly Property Id As Guid
Value
PlatForm::Guid Guid Guid

The provider identifier for this channel.

Attributes

Remarks

The value of the Id depends on how the LoggingChannel is constructed as described in the following table:

Constructor usedThe value of Id
LoggingChannel(String) The channel will be operating in Windows 8.1 compatibility mode and will return 4bd2826e-54a1-4ba9-bf63-92b73ea1ac4a which is the GUID for the Microsoft-Windows-Diagnostics-LoggingChannel manifest.
LoggingChannel(String, LoggingChannelOptions) The GUID will be determined by hashing the name parameter passed to the LoggingChannel constructor.
LoggingChannel(String, LoggingChannelOptions, Guid) The value is the same as the Id parameter passed to the LoggingChannel constructor.

Level Level Level

Gets the minimum level at which any session is listening to events from this channel.

public : LoggingLevel Level { get; }public LoggingLevel Level { get; }Public ReadOnly Property Level As LoggingLevel
Value
LoggingLevel LoggingLevel LoggingLevel

The event level required for the session to listen to an event from this channel.

Attributes

Remarks

This value is only valid if the Enabled property is set to true.

Name Name Name

Gets the name of the current LoggingChannel.

public : PlatForm::String Name { get; }public string Name { get; }Public ReadOnly Property Name As string
Value
PlatForm::String string string

The name.

Attributes

Methods

Close() Close() Close()

Ends logging on the current logging channel.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net
Attributes

Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Dispose
Attributes

IsEnabled() IsEnabled() IsEnabled()

Indicates whether at least one session is listening for events from the channel.

public : PlatForm::Boolean IsEnabled()public bool IsEnabled()Public Function IsEnabled() As bool
Returns
PlatForm::Boolean bool bool

Returns true if at least one session is listening for events from the channel, and otherwise false.

Attributes

Remarks

This property is functionally equivalent to Enabled

See Also

IsEnabled(LoggingLevel) IsEnabled(LoggingLevel) IsEnabled(LoggingLevel)

Indicates whether at least one session is listening for events with the specified event severity level from the channel.

public : PlatForm::Boolean IsEnabled(LoggingLevel level)public bool IsEnabled(LoggingLevel level)Public Function IsEnabled(level As LoggingLevel) As bool
Parameters
level
LoggingLevel LoggingLevel LoggingLevel

The event severity level.

Returns
PlatForm::Boolean bool bool

Returns true if at least one session is listening for events with the specified level from the channel, and otherwise false.

Attributes

Remarks

This property is equivalent to channel.Enabled && channel.Level <= level.

See Also

IsEnabled(LoggingLevel, Int64) IsEnabled(LoggingLevel, Int64) IsEnabled(LoggingLevel, Int64)

Indicates whether at least one session is listening for events with the specified level and keywords from this channel.

public : PlatForm::Boolean IsEnabled(LoggingLevel level, long keywords)public bool IsEnabled(LoggingLevel level, Int64 keywords)Public Function IsEnabled(level As LoggingLevel, keywords As Int64) As bool
Parameters
level
LoggingLevel LoggingLevel LoggingLevel

The event severity level.

keywords
long Int64 Int64

The keywords. Each bit of the keywords value represents an event category.

Returns
PlatForm::Boolean bool bool

Returns true if at least one session is listening for events with the specified level and keywords from the channel, and otherwise false.

Attributes
See Also

LogEvent(String) LogEvent(String) LogEvent(String)

LogEvent(String, LoggingFields) LogEvent(String, LoggingFields) LogEvent(String, LoggingFields)

Logs an event with the specified name and fields.

public : void LogEvent(PlatForm::String eventName, LoggingFields fields)public void LogEvent(String eventName, LoggingFields fields)Public Function LogEvent(eventName As String, fields As LoggingFields) As void
Parameters
eventName
PlatForm::String String String

The name for this event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event. May be null.

Attributes
See Also

LogEvent(String, LoggingFields, LoggingLevel) LogEvent(String, LoggingFields, LoggingLevel) LogEvent(String, LoggingFields, LoggingLevel)

Logs an event with the specified name, fields, and level.

public : void LogEvent(PlatForm::String eventName, LoggingFields fields, LoggingLevel level)public void LogEvent(String eventName, LoggingFields fields, LoggingLevel level)Public Function LogEvent(eventName As String, fields As LoggingFields, level As LoggingLevel) As void
Parameters
eventName
PlatForm::String String String

The name for this event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event. May be null.

level
LoggingLevel LoggingLevel LoggingLevel

The level of detail for this event.

Attributes
See Also

LogEvent(String, LoggingFields, LoggingLevel, LoggingOptions) LogEvent(String, LoggingFields, LoggingLevel, LoggingOptions) LogEvent(String, LoggingFields, LoggingLevel, LoggingOptions)

Logs an event with the specified name, fields, level, and options.

public : void LogEvent(PlatForm::String eventName, LoggingFields fields, LoggingLevel level, LoggingOptions options)public void LogEvent(String eventName, LoggingFields fields, LoggingLevel level, LoggingOptions options)Public Function LogEvent(eventName As String, fields As LoggingFields, level As LoggingLevel, options As LoggingOptions) As void
Parameters
eventName
PlatForm::String String String

The name for this event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event. May be null.

level
LoggingLevel LoggingLevel LoggingLevel

The level of detail for this event.

options
LoggingOptions LoggingOptions LoggingOptions

The options for this event. Pass null to use the default options. The options are for advanced scenarios. The default values are designed to work well for most events.

Attributes
See Also

LogMessage(String) LogMessage(String) LogMessage(String)

Logs a message to the current LoggingChannel.

public : void LogMessage(PlatForm::String eventString)public void LogMessage(String eventString)Public Function LogMessage(eventString As String) As void
Parameters
eventString
PlatForm::String String String

The message to log.

Attributes
See Also

LogMessage(String, LoggingLevel) LogMessage(String, LoggingLevel) LogMessage(String, LoggingLevel)

Logs a message to the current LoggingChannel with the specified LoggingLevel.

public : void LogMessage(PlatForm::String eventString, LoggingLevel level)public void LogMessage(String eventString, LoggingLevel level)Public Function LogMessage(eventString As String, level As LoggingLevel) As void
Parameters
eventString
PlatForm::String String String

The message to log.

level
LoggingLevel LoggingLevel LoggingLevel

The logging level.

Attributes
See Also

LogValuePair(String, Int32) LogValuePair(String, Int32) LogValuePair(String, Int32)

Logs data to the current LoggingChannel.

public : void LogValuePair(PlatForm::String value1, int value2)public void LogValuePair(String value1, Int32 value2)Public Function LogValuePair(value1 As String, value2 As Int32) As void
Parameters
value1
PlatForm::String String String

The string to associate with value2.

value2
int Int32 Int32

The value to associate with value1.

Attributes

Remarks

Call the LogValuePair method to log data as a key-value pair to the current LoggingChannel.

See Also

LogValuePair(String, Int32, LoggingLevel) LogValuePair(String, Int32, LoggingLevel) LogValuePair(String, Int32, LoggingLevel)

Logs data to the current LoggingChannel with the specified LoggingLevel.

public : void LogValuePair(PlatForm::String value1, int value2, LoggingLevel level)public void LogValuePair(String value1, Int32 value2, LoggingLevel level)Public Function LogValuePair(value1 As String, value2 As Int32, level As LoggingLevel) As void
Parameters
value1
PlatForm::String String String

The string to associate with value2.

value2
int Int32 Int32

The value to associate with value1.

level
LoggingLevel LoggingLevel LoggingLevel

The logging level.

Attributes
See Also

StartActivity(String) StartActivity(String) StartActivity(String)

Writes an activity start event and creates a LoggingActivity object.

public : LoggingActivity StartActivity(PlatForm::String startEventName)public LoggingActivity StartActivity(String startEventName)Public Function StartActivity(startEventName As String) As LoggingActivity
Parameters
startEventName
PlatForm::String String String

The name for this event.

Returns

Returns an object that represents the new activity.

Attributes
See Also

StartActivity(String, LoggingFields) StartActivity(String, LoggingFields) StartActivity(String, LoggingFields)

Writes an activity start event with the specified fields and creates a LoggingActivity object.

public : LoggingActivity StartActivity(PlatForm::String startEventName, LoggingFields fields)public LoggingActivity StartActivity(String startEventName, LoggingFields fields)Public Function StartActivity(startEventName As String, fields As LoggingFields) As LoggingActivity
Parameters
startEventName
PlatForm::String String String

The name for this event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event.

Returns

Returns an object that represents the new activity.

Attributes
See Also

StartActivity(String, LoggingFields, LoggingLevel) StartActivity(String, LoggingFields, LoggingLevel) StartActivity(String, LoggingFields, LoggingLevel)

Writes an activity start event with the specified fields and level, and creates a LoggingActivity object.

public : LoggingActivity StartActivity(PlatForm::String startEventName, LoggingFields fields, LoggingLevel level)public LoggingActivity StartActivity(String startEventName, LoggingFields fields, LoggingLevel level)Public Function StartActivity(startEventName As String, fields As LoggingFields, level As LoggingLevel) As LoggingActivity
Parameters
startEventName
PlatForm::String String String

The name for this event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event. May be **null **.

level
LoggingLevel LoggingLevel LoggingLevel

The level of detail for this event.

Returns

Returns an object that represents the new activity.

Attributes
See Also

StartActivity(String, LoggingFields, LoggingLevel, LoggingOptions) StartActivity(String, LoggingFields, LoggingLevel, LoggingOptions) StartActivity(String, LoggingFields, LoggingLevel, LoggingOptions)

Writes an activity start event with the specified fields, level, and options, and creates a LoggingActivity object.

public : LoggingActivity StartActivity(PlatForm::String startEventName, LoggingFields fields, LoggingLevel level, LoggingOptions options)public LoggingActivity StartActivity(String startEventName, LoggingFields fields, LoggingLevel level, LoggingOptions options)Public Function StartActivity(startEventName As String, fields As LoggingFields, level As LoggingLevel, options As LoggingOptions) As LoggingActivity
Parameters
startEventName
PlatForm::String String String

The name for this event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event. May be null.

level
LoggingLevel LoggingLevel LoggingLevel

The level of detail for this event.

options
LoggingOptions LoggingOptions LoggingOptions

The options for this event. Pass null to use the default options. The options are for advanced scenarios. The default values are designed to work well for most events.

Returns

Returns an object that represents the new activity.

Attributes

Remarks

If you provide options, LoggingOptions.ActivityId and LoggingOptions.Opcode are ignored because the new LoggingActivity object's options will be set as follows:

The Id is automatically generated.

The opcode is set to LoggingOptions.Opcode.Start

See Also

Events

LoggingEnabled LoggingEnabled LoggingEnabled

Raised when the logging channel is attached to a LoggingSession or other event tracing and debugging tools.

public : event TypedEventHandler LoggingEnabledpublic event TypedEventHandler LoggingEnabledPublic Event LoggingEnabled
Attributes

Remarks

The LoggingEnabled event is raised when a channel is consumed by a session within the app's process, or by a kernel-mode ETW session started with a debugging or performance analysis tool.

See Also