LoggingChannel
LoggingChannel
LoggingChannel
LoggingChannel
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// You can use this class in JavaScript.
- Attributes
| 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 mode | Windows 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) 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)// You can use this method in JavaScript.
- name
- PlatForm::String String String String
The name of the logging channel.
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) 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)// You can use this method in JavaScript.
- name
- PlatForm::String String String String
The name of the logging channel.
The channel options. Pass null to specify the default options.
- See Also
LoggingChannel(String, LoggingChannelOptions, Guid) 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)// You can use this method in JavaScript.
- name
- PlatForm::String String String String
The name of the logging channel.
The channel options. Pass null to specify the default options.
- id
- PlatForm::Guid Guid Guid Guid
The channel identifier to use instead of the automatically generated identifier.
- See Also
Properties
Enabled 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// You can use this property in JavaScript.
- Value
- PlatForm::Boolean bool bool bool
Returns true if at least one session is listening for events from the channel, and otherwise false.
Id 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// You can use this property in JavaScript.
- Value
- PlatForm::Guid Guid Guid Guid
The provider identifier for this channel.
Remarks
The value of the Id depends on how the LoggingChannel is constructed as described in the following table:
| Constructor used | The 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 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// You can use this property in JavaScript.
The event level required for the session to listen to an event from this channel.
Remarks
This value is only valid if the Enabled property is set to true.
Name 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// You can use this property in JavaScript.
- Value
- PlatForm::String string string string
The name.
Methods
Close() 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// You can use this method in JavaScript.
Dispose() 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 Disposevoid Dispose()
IsEnabled() 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// You can use this method in JavaScript.
Returns true if at least one session is listening for events from the channel, and otherwise false.
Remarks
This property is functionally equivalent to Enabled
- See Also
IsEnabled(LoggingLevel) 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// You can use this method in JavaScript.
The event severity level.
Returns true if at least one session is listening for events with the specified level from the channel, and otherwise false.
Remarks
This property is equivalent to channel.Enabled && channel.Level <= level.
- See Also
IsEnabled(LoggingLevel, Int64) 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// You can use this method in JavaScript.
The event severity level.
- keywords
- long Int64 Int64 Int64
The keywords. Each bit of the keywords value represents an event category.
Returns true if at least one session is listening for events with the specified level and keywords from the channel, and otherwise false.
- See Also
LogEvent(String) LogEvent(String) LogEvent(String) LogEvent(String)
Logs an event with the specified name.
public : void LogEvent(PlatForm::String eventName)public void LogEvent(String eventName)Public Function LogEvent(eventName As String) As void// You can use this method in JavaScript.
- eventName
- PlatForm::String String String String
The name for this event.
LogEvent(String, LoggingFields) 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// You can use this method in JavaScript.
- eventName
- PlatForm::String String String String
The name for this event.
The fields for this event. May be null.
LogEvent(String, LoggingFields, LoggingLevel) 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// You can use this method in JavaScript.
- eventName
- PlatForm::String String String String
The name for this event.
The fields for this event. May be null.
The level of detail for this event.
LogEvent(String, LoggingFields, LoggingLevel, LoggingOptions) 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// You can use this method in JavaScript.
- eventName
- PlatForm::String String String String
The name for this event.
The fields for this event. May be null.
The level of detail for this event.
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.
LogMessage(String) 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// You can use this method in JavaScript.
- eventString
- PlatForm::String String String String
The message to log.
- See Also
LogMessage(String, LoggingLevel) 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// You can use this method in JavaScript.
- eventString
- PlatForm::String String String String
The message to log.
The logging level.
- See Also
LogValuePair(String, Int32) 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// You can use this method in JavaScript.
- value1
- PlatForm::String String String String
The string to associate with value2.
- value2
- int Int32 Int32 Int32
The value to associate with value1.
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) 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// You can use this method in JavaScript.
- value1
- PlatForm::String String String String
The string to associate with value2.
- value2
- int Int32 Int32 Int32
The value to associate with value1.
The logging level.
- See Also
StartActivity(String) 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// You can use this method in JavaScript.
- startEventName
- PlatForm::String String String String
The name for this event.
Returns an object that represents the new activity.
StartActivity(String, LoggingFields) 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// You can use this method in JavaScript.
- startEventName
- PlatForm::String String String String
The name for this event.
The fields for this event.
Returns an object that represents the new activity.
StartActivity(String, LoggingFields, LoggingLevel) 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// You can use this method in JavaScript.
- startEventName
- PlatForm::String String String String
The name for this event.
The fields for this event. May be **null **.
The level of detail for this event.
Returns an object that represents the new activity.
StartActivity(String, LoggingFields, LoggingLevel, LoggingOptions) 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// You can use this method in JavaScript.
- startEventName
- PlatForm::String String String String
The name for this event.
The fields for this event. May be null.
The level of detail for this event.
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 an object that represents the new activity.
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 LoggingEnabled
Raised when the logging channel is attached to a LoggingSession or other event tracing and debugging tools.
public : event TypedEventHandler LoggingEnabled<ILoggingChannel, object>public event TypedEventHandler LoggingEnabled<ILoggingChannel, object>Public Event LoggingEnabled<ILoggingChannel, object>// You can use this event in JavaScript.
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.