FileLoggingSession FileLoggingSession FileLoggingSession FileLoggingSession Class

Represents the destination of logged messages from LoggingChannel instances.

Syntax

Declaration

public sealed class FileLoggingSessionpublic sealed class FileLoggingSessionPublic NotInheritable Class FileLoggingSessionpublic sealed class FileLoggingSession

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 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 summary

Initializes a new instance of the FileLoggingSession class.

Properties summary

Gets the name of the logging session.

Methods summary

Adds a logging channel to the current logging session.

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.

Ends the current logging session.

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

Removes the specified logging channel from the current logging session.

Events summary

Raised when a log file is saved.

Constructors

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

    Initializes a new instance of the FileLoggingSession class.

    public FileLoggingSession(String name)public New(String name)Public Sub New(name As String)public FileLoggingSession(String name)

    Parameters

    • name
      System.String
      System.String
      System.String
      System.String

      The name of the logging session.

Properties

  • Name
    Name
    Name
    Name

    Gets the name of the logging session.

    public string Name { get; }public string Name { get; }Public ReadOnly Property Name As stringpublic string Name { get; }

    Property Value

    • string
      string
      string
      string

      The session name.

Methods

  • AddLoggingChannel(ILoggingChannel)
    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 voidpublic void AddLoggingChannel(ILoggingChannel loggingChannel)

    Parameters

    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)
    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 voidpublic void AddLoggingChannel(ILoggingChannel loggingChannel, LoggingLevel maxLevel)

    Parameters

    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()
    Close()

    Ends the current logging session.

    public void Close()public void Close()Public Function Close() As voidpublic void Close()
  • CloseAndSaveToFileAsync()
    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 )public IAsyncOperation<StorageFile> CloseAndSaveToFileAsync()

    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.

    Remarks

    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 Close().

  • RemoveLoggingChannel(ILoggingChannel)
    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 voidpublic void RemoveLoggingChannel(ILoggingChannel loggingChannel)

    Parameters

Events

  • LogFileGenerated
    LogFileGenerated
    LogFileGenerated
    LogFileGenerated

    Raised when a log file is saved.

    public event TypedEventHandler LogFileGeneratedpublic event TypedEventHandler LogFileGeneratedPublic Event LogFileGeneratedpublic event TypedEventHandler LogFileGenerated

    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.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.Foundation.Diagnostics.dll