LoggingActivity LoggingActivity LoggingActivity Class

Definition

Creates Event Tracing for Windows (ETW) events that mark the start and end of a group of related events.

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

Remarks

Windows 10 The LoggingActivity class has been extended in the following ways:+ Now implements ILoggingTarget which provides activity start and stop methods that provide control over the format and contents of the Start and Stop events.

  • Now implements methods to log events. Events are automatically tagged with the LoggingActivity's GUID.
  • Activities can be nested. Every LoggingActivity object is attached to a LoggingChannel object. All events created by the LoggingActivity object are written through the attached LoggingChannel object.

Constructors

LoggingActivity(String, ILoggingChannel) LoggingActivity(String, ILoggingChannel) LoggingActivity(String, ILoggingChannel)

Initializes a new instance of the LoggingActivity class for the specified LoggingChannel in Windows 8.1 compatibility mode.

public LoggingActivity(String activityName, ILoggingChannel loggingChannel)public LoggingActivity(String activityName, ILoggingChannel loggingChannel)Public Sub New(activityName As String, loggingChannel As ILoggingChannel)
Parameters
activityName
System.String System.String System.String

The name of the logging activity.

loggingChannel
ILoggingChannel ILoggingChannel ILoggingChannel

The logging channel.

Attributes

Remarks

Windows 10 Two modes of operation are now supported: Windows 8.1 compatibility mode and the new behavior supported by Windows 10 and later.+ For Windows 8.1 compatibility mode, create the object using a constructor.

Windows 8.1 compatibility modeWindows 10 and later specific behavior
The start event generated by the constructor is formatted for compatibility with the manifest used by LoggingChannel. The start event name is hard-coded as “LogActivityStart” + Level. The event will be a manifest-based event or a self-describing event depending on the operating mode of the underlying channel.The start event generated by the StartActivity method follows the conventions of LoggingChannel.LogEvent and will always use a self-describing, i.e. not manifest-based, event encoding. The event name is based on the startEventName parameter.
The stop event generated by Close() or Dispose() is formatted for compatibility with the manifest used by LoggingChannel. The stop event name is hard-coded as “LogActivityStop” + Level. The event will be a manifest-based event or a self-describing event, depending on the operating mode of the underlying channel.The Stop event generated by Close() or Dispose() will follow the conventions of LoggingChannel.LogEvent and will use the self-describing event encoding. The activity name will be used as the stop event name.
The destructor/finalizer will invoke Close().The destructor/finalizer will not invoke Close().

LoggingActivity(String, ILoggingChannel, LoggingLevel) LoggingActivity(String, ILoggingChannel, LoggingLevel) LoggingActivity(String, ILoggingChannel, LoggingLevel)

Initializes a new instance of the LoggingActivity class for the specified LoggingChannel and LoggingLevel in Windows 8.1 compatibility mode.

public LoggingActivity(String activityName, ILoggingChannel loggingChannel, LoggingLevel level)public LoggingActivity(String activityName, ILoggingChannel loggingChannel, LoggingLevel level)Public Sub New(activityName As String, loggingChannel As ILoggingChannel, level As LoggingLevel)
Parameters
activityName
System.String System.String System.String

The name of the logging activity.

loggingChannel
ILoggingChannel ILoggingChannel ILoggingChannel

The logging channel.

level
LoggingLevel LoggingLevel LoggingLevel

The logging level.

Attributes

Properties

Channel Channel Channel

Returns the channel associated with this activity.

public LoggingChannel Channel { get; }public LoggingChannel Channel { get; }Public ReadOnly Property Channel As LoggingChannel
Value
LoggingChannel LoggingChannel LoggingChannel

The channel associated with this activity.

Attributes

Id Id Id

Gets the identifier for the current logging activity.

public Guid Id { get; }public Guid Id { get; }Public ReadOnly Property Id As Guid
Value
System.Guid System.Guid System.Guid

The identifier.

Attributes

Name Name Name

Gets the name of the current logging activity.

public 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 the current logging activity.

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

Remarks

Windows 10 In addition to ending the current logging activity, generates a stop event for the activity.

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 associated with this activity.

public bool 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 associated with this activity, and otherwise false.

Attributes

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 associated with this activity.

public bool 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 associated with this activity, and otherwise false.

Attributes

Remarks

This function is equivalent to LoggingChannel.IsEnabled(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 the channel associated with this activity.

public bool 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 associated with this activity, and otherwise false.

Attributes

Remarks

This function is equivalent to LoggingChannel.IsEnabled(level, keywords).

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

Remarks

The level is set to LoggingLevel.Verbose.

Methods that accept a LoggingFields parameter also accept null. A null value is semantically equivalent to a newly-constructed or cleared LoggingFields object and represents an empty payload.

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 severity level 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 severity level 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

Remarks

If you provide options,LoggingOptions.ActivityId and LoggingOptions.RelatedActivityId are ignored because the activity object automatically manages these values for the event.

eventName should not be used as a payload field. For example, use LogEvent(“MyEvent”, fieldsWithStringData) instead of LogEvent(stringData).

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 the start event.

Returns

An object the represents the new activity.

Attributes

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

Writes an activity start event with 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 the start event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event.

Returns

An object that represents the new activity.

Attributes

Remarks

Methods that accept a LoggingFields parameter also accept null. A null value is semantically equivalent to a newly-constructed or cleared LoggingFields object and represents an empty payload.

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 the start 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

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

An object that represents the new activity.

Attributes

Remarks

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

The RelatedId is set using this LoggingActivity's Id.

The Id is automatically generated.

The opcode is set to LoggingOptions.Opcode.Start

StopActivity(String) StopActivity(String) StopActivity(String)

Marks the activity as closed/disposed and generates a stop event with the specified event name.

public void StopActivity(String stopEventName)public void StopActivity(String stopEventName)Public Function StopActivity(stopEventName As String) As void
Parameters
stopEventName
System.String System.String System.String

The name for the stop event.

Attributes

Remarks

The level for this event is the same as the level specified for the start event.

This function will fail if the activity has already been closed or disposed.

StopActivity(String, LoggingFields) StopActivity(String, LoggingFields) StopActivity(String, LoggingFields)

Marks the activity as closed/disposed and generates a stop event with the specified event name and fields.

public void StopActivity(String stopEventName, LoggingFields fields)public void StopActivity(String stopEventName, LoggingFields fields)Public Function StopActivity(stopEventName As String, fields As LoggingFields) As void
Parameters
stopEventName
System.String System.String System.String

The name for this event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event. May be null.

Attributes

Remarks

Methods that accept a LoggingFields parameter also accept null. A null value is semantically equivalent to a newly-constructed or cleared LoggingFields object and represents an empty payload.

StopActivity(String, LoggingFields, LoggingOptions) StopActivity(String, LoggingFields, LoggingOptions) StopActivity(String, LoggingFields, LoggingOptions)

Marks the activity as closed/disposed and generates a stop event with the specified event name, fields, and options.

public void StopActivity(String stopEventName, LoggingFields fields, LoggingOptions options)public void StopActivity(String stopEventName, LoggingFields fields, LoggingOptions options)Public Function StopActivity(stopEventName As String, fields As LoggingFields, options As LoggingOptions) As void
Parameters
stopEventName
System.String System.String System.String

The name for the stop event.

fields
LoggingFields LoggingFields LoggingFields

The fields for this event. May be null.

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

Remarks

If you pass LoggingOptions:

LoggingOptions.Keywords is ignored because the keywords for the stop event are based on the keywords for the start event.

LoggingOptions.Opcode is ignored because the opcode is always LoggingOptions.Stop for a Stop event.

LoggingOptions.ActivityId is ignored because the Id from this LoggingActivity is used.

LoggingOptions.RelatedActivityId is ignored because it is only used for the start event.

See Also