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(String name)public LoggingChannel(String name)Public Sub New(name As String)
Parameters
name
System.String System.String System.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).

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

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

public LoggingChannel(String name, LoggingChannelOptions options)public LoggingChannel(String name, LoggingChannelOptions options)Public Sub New(name As String, options As LoggingChannelOptions)
Parameters
name
System.String System.String System.String

The name of the logging channel.

options
LoggingChannelOptions LoggingChannelOptions LoggingChannelOptions

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

Attributes

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(String name, LoggingChannelOptions options, Guid id)public LoggingChannel(String name, LoggingChannelOptions options, Guid id)Public Sub New(name As String, options As LoggingChannelOptions, id As Guid)
Parameters
name
System.String System.String System.String

The name of the logging channel.

options
LoggingChannelOptions LoggingChannelOptions LoggingChannelOptions

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

id
System.Guid System.Guid System.Guid

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

Attributes

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
bool 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
System.Guid System.Guid System.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
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
bool 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

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
bool 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.

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, Int64 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
System.Int64 System.Int64 System.Int64

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

Returns
bool 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

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

Logs an event with the specified name.

public void LogEvent(String eventName)public void LogEvent(String eventName)Public Function LogEvent(eventName As String) As void
Parameters
eventName
System.String System.String System.String

The name for this event.

Attributes

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

Logs an event with the specified name and fields.

public void LogEvent(String eventName, LoggingFields fields)public void LogEvent(String eventName, LoggingFields fields)Public Function LogEvent(eventName As String, fields As LoggingFields) As void
Parameters
eventName
System.String System.String System.String

The name for this event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event. May be null.

Attributes

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(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
System.String System.String System.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

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(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
System.String System.String System.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

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

Logs a message to the current LoggingChannel.

public void LogMessage(String eventString)public void LogMessage(String eventString)Public Function LogMessage(eventString As String) As void
Parameters
eventString
System.String System.String System.String

The message to log.

Attributes

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

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

public void LogMessage(String eventString, LoggingLevel level)public void LogMessage(String eventString, LoggingLevel level)Public Function LogMessage(eventString As String, level As LoggingLevel) As void
Parameters
eventString
System.String System.String System.String

The message to log.

level
LoggingLevel LoggingLevel LoggingLevel

The logging level.

Attributes

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

Logs data to the current LoggingChannel.

public void LogValuePair(String value1, Int32 value2)public void LogValuePair(String value1, Int32 value2)Public Function LogValuePair(value1 As String, value2 As Int32) As void
Parameters
value1
System.String System.String System.String

The string to associate with value2.

value2
System.Int32 System.Int32 System.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.

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(String value1, Int32 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
System.String System.String System.String

The string to associate with value2.

value2
System.Int32 System.Int32 System.Int32

The value to associate with value1.

level
LoggingLevel LoggingLevel LoggingLevel

The logging level.

Attributes

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

Writes an activity start event and creates a LoggingActivity object.

public LoggingActivity StartActivity(String startEventName)public LoggingActivity StartActivity(String startEventName)Public Function StartActivity(startEventName As String) As LoggingActivity
Parameters
startEventName
System.String System.String System.String

The name for this event.

Returns

Returns an object that represents the new activity.

Attributes

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(String startEventName, LoggingFields fields)public LoggingActivity StartActivity(String startEventName, LoggingFields fields)Public Function StartActivity(startEventName As String, fields As LoggingFields) As LoggingActivity
Parameters
startEventName
System.String System.String System.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

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(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
System.String System.String System.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

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(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
System.String System.String System.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

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