File​Logging​Session File​Logging​Session File​Logging​Session Class

Definition

Represents the destination of logged messages from LoggingChannel instances.

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

Remarks

Use the FileLoggingSession class to log messages and data to a file continuously as your app runs. You can view the log files by using the Windows Performance Toolkit (WPT) and other utilities like tracerpt.exe.

Add LoggingChannel instances to a FileLoggingSession, and call FileLoggingSession instance methods to remove channels, dispose, and perform other operations. The number of channels is not currently limited.

Windows Server 2012 R2Windows 8.1 Each app is limited to 4 active channels, and channels must have unique names.

The FileLoggingSession class sends logged messages to disk files as they are logged. The FileLoggingSession class uses sequential logging, which means that all messages are sent to a disk file, and a sequential history of messages is retained. This is distinct from the LoggingSession class, which sends logged messages to disk on-demand, i.e. when the app detects a problem and saves the in-memory messages for analysis.

Use the FileLoggingSession class when you know that all messages need to be saved, usually over a long period of time, and when the app can't be burdened with on-demand saving steps. Like the@Windows.Foundation.Diagnostics.LoggingSession?text=LoggingSession class, LoggingChannel instances are added to a FileLoggingSession instance, and the FileLoggingSession instance has methods to remove channels and dispose. FileLoggingSession instances are initialized with a delegate to a new file callback, which notifies the app when a log file rollover has occurred. The feature invokes the delegate when the current internal log file has reached capacity and a new file is being created for continued sequential logging. The delegate callback can also be called at suspend boundaries, or when the FileLoggingSession is disposed.

When the LogFileGenerated event is invoked, the app receives an StorageFile that represents the now-closed log file. The app can forward the log file for processing in an application-defined way. After this, the session continues logging to a newly created and now-open current log file. When this log file reaches capacity, the callback delegate is invoked again for the new file, and the process repeats.

When you are done logging events, call CloseAndSaveToFileAsync in order to get the last log file since the last log file may be still open if it has not yet reached capacity. You can also use CloseAndSaveToFileAsync to close the session and get access to the last log file. Note that if the last log file was empty, or if all log files have already been reported by the LogFileGenerated method, the CloseAndSaveToFileAsync method will return null.

The log files are created in the of the ApplicationData\Logs folder.

The name of each log file is based on the name of the session plus an index. The index is reset each time a new session is created. Each time a log file reaches maximum size, it is closed, the index is incremented, and a new log file is opened using the new index. (As a consequence, each time you restart an app, it will begin overwriting the log files generated by the previous instance of the app.)

You can add a handler for the LogFileGenerated event so that your app is notified each time a log file is closed.

If you do not use the LogFileGenerated event or the CloseAndSaveToFileAsync method, the FileLoggingSession will not delete stale log files (though a new session may overwrite files generated by a previous session). Your app is responsible for locating and cleaning up the log files as needed.

Before a log file is provided to an app via the LogFileGenerated event or the CloseAndSaveToFileAsync method, it is renamed to a special log file name. The same log file name is always used, so new logs will overwrite older logs. In this way, the LogFileGenerated event and CloseAndSaveToFileAsync methods help prevent stale log files from wasting space in the ApplicationData folder.

FileLoggingSession will close the current log file and start a new log file when the current log file reaches 256KB.

Constructors

FileLoggingSession(String) FileLoggingSession(String) FileLoggingSession(String)

Initializes a new instance of the FileLoggingSession class.

public FileLoggingSession(String name)public FileLoggingSession(String name)Public Sub New(name As String)
Parameters
name
System.String System.String System.String

The name of the logging session.

Attributes

Properties

Name Name Name

Gets the name of the logging session.

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

The session name.

Attributes

Methods

AddLoggingChannel(ILoggingChannel) AddLoggingChannel(ILoggingChannel) AddLoggingChannel(ILoggingChannel)

Adds a logging channel to the current logging session.

public void AddLoggingChannel(ILoggingChannel loggingChannel)public void AddLoggingChannel(ILoggingChannel loggingChannel)Public Function AddLoggingChannel(loggingChannel As ILoggingChannel) As void
Parameters
loggingChannel
ILoggingChannel ILoggingChannel ILoggingChannel

The logging channel to add.

Attributes

Remarks

The logging level is set to LoggingLevel.Verbose. The **LoggingChannel ** will accept all events.

Adding a channel to a session more than once updates the level.

AddLoggingChannel(ILoggingChannel, LoggingLevel) AddLoggingChannel(ILoggingChannel, LoggingLevel) AddLoggingChannel(ILoggingChannel, LoggingLevel)

Adds a logging channel to the current logging session. The logging channel only accepts events that have a logging level at or above the specified logging level.

public void AddLoggingChannel(ILoggingChannel loggingChannel, LoggingLevel maxLevel)public void AddLoggingChannel(ILoggingChannel loggingChannel, LoggingLevel maxLevel)Public Function AddLoggingChannel(loggingChannel As ILoggingChannel, maxLevel As LoggingLevel) As void
Parameters
loggingChannel
ILoggingChannel ILoggingChannel ILoggingChannel

The logging channel to add.

maxLevel
LoggingLevel LoggingLevel LoggingLevel

The minimum logging level that an event must have to be accepted by the session.

Attributes

Remarks

maxLevel specifies the which events from the channel the session will accept and which are ignored. It does not change the level of the channel itself.

Close() Close() Close()

Ends the current logging session.

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

CloseAndSaveToFileAsync() CloseAndSaveToFileAsync() CloseAndSaveToFileAsync()

Ends the current logging session and saves it to a file.

public IAsyncOperation<StorageFile> CloseAndSaveToFileAsync()public IAsyncOperation<StorageFile> CloseAndSaveToFileAsync()Public Function CloseAndSaveToFileAsync() As IAsyncOperation( Of StorageFile )
Returns

When this method completes, it returns the new file as a StorageFile. Returns NULL if there are no events in the session or if logging has just rolled over into a new file that doesn't contain events yet.

Attributes

Remarks

FileLoggingSession.CloseAndSaveToFileAsync closes the current logging session. If there is a handler for the LogFileGenerated method, and it has been called but not returned, the function waits for the handler to return. If there is any data in the current log file that has not already been reported with the LogFileGenerated event, the function returns a StorageFile representing that file.

Otherwise, the function returns NULL. This can happen if the current log file is empty, or if all log files have already been reported via the LogFileGenerated event. Note that CloseAndSaveToFileAsync might return NULL even if data was recorded and even if there is no LogFileGenerated event. This can happen if the log file became full and was closed, and a new log file was opened immediately before CloseAndSaveToFileAsync was called.

This function is equivalent to FileLoggingSession.Close.

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

RemoveLoggingChannel(ILoggingChannel) RemoveLoggingChannel(ILoggingChannel) RemoveLoggingChannel(ILoggingChannel)

Removes the specified logging channel from the current logging session.

public void RemoveLoggingChannel(ILoggingChannel loggingChannel)public void RemoveLoggingChannel(ILoggingChannel loggingChannel)Public Function RemoveLoggingChannel(loggingChannel As ILoggingChannel) As void
Parameters
loggingChannel
ILoggingChannel ILoggingChannel ILoggingChannel

The logging channel to remove.

Attributes

Events

LogFileGenerated LogFileGenerated LogFileGenerated

Raised when a log file is saved.

public event TypedEventHandler LogFileGeneratedpublic event TypedEventHandler LogFileGeneratedPublic Event LogFileGenerated
Attributes

Remarks

If no handler is registered for this event, log files will accumulate in the ApplicationData folder.

This event is raised when the session rolls over from one log file to the next. If the file needs to be preserved, your handler must move the file to a new location before returning. The FileLoggingSession might delete or overwrite the file anytime after your handler has returned.

When you register a handler for this event, if log files had been saved while there was no handler registered for this event, your newly-added handler will immediately be invoked once for each of the previously-saved log files.

Your handler must do any processing necessary to preserve the file.

This event is not raised for the last log file because the last log file does not roll over. Use CloseAndSaveToFileAsync to access the last log file.

See Also