FileLoggingSession 类

定义

命名空间:

Windows.Foundation.Diagnostics

表示来自 LoggingChannel 实例的记录消息的目标。

public ref class FileLoggingSession sealed : IFileLoggingSession, IClosable

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Foundation.Diagnostics.IFileLoggingSessionFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class FileLoggingSession final : IFileLoggingSession, IClosable

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Foundation.Diagnostics.IFileLoggingSessionFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class FileLoggingSession : System.IDisposable, IFileLoggingSession

function FileLoggingSession(name)

Public NotInheritable Class FileLoggingSession
Implements IDisposable, IFileLoggingSession

继承

Object Platform::Object IInspectable FileLoggingSession

属性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

实现

IClosable IDisposable IFileLoggingSession

Windows 要求

设备系列	Windows 10 (在 10.0.10240.0 中引入)
API contract	Windows.Foundation.UniversalApiContract (在 v1.0 中引入)

注解

使用 FileLoggingSession 类在应用运行时将消息和数据连续记录到文件中。 可以使用 Windows Performance Toolkit (WPT) 和其他实用工具（如 tracerpt.exe）查看日志文件。

将 LoggingChannel 实例添加到 FileLoggingSession，并调用 FileLoggingSession 实例方法以删除通道、释放和执行其他操作。 通道数目前不受限制。

注意

在 Windows Server 2012 R2 和 Windows 8.1 中，每个应用限制为 4 个活动通道，并且通道必须具有唯一的名称。

当填充缓冲区或用户调用 CloseAndSaveToFileAsync 时，FileLoggingSession 类会将记录的消息发送到磁盘文件。 FileLoggingSession 类使用顺序日志记录，这意味着所有消息都发送到磁盘文件，并保留消息的顺序历史记录。 这不同于 LoggingSession 类，后者将记录的消息按需发送到磁盘，即当应用检测到问题并保存内存中消息进行分析时。

如果知道需要保存所有消息（通常是很长一段时间），并且应用无法承受按需保存步骤的负担，请使用 FileLoggingSession 类。 与 LoggingSession 类一样， LoggingChannel 实例将添加到 FileLoggingSession 实例， FileLoggingSession 实例具有删除通道和释放的方法。 FileLoggingSession 实例使用对新文件回调的委托进行初始化，这会在发生日志文件滚动更新时通知应用。 当当前内部日志文件达到容量并且正在为连续日志记录创建一个新文件时，该功能将调用委托。 还可以在挂起边界或释放 FileLoggingSession 时调用委托回调。

调用 LogFileGenerated 事件时，应用将收到表示现已关闭的日志文件的 StorageFile 。 应用可以转发日志文件，以应用程序定义的方式进行处理。 在此之后，会话将继续记录到新建的、现在打开的当前日志文件。 当此日志文件达到容量时，将再次为新文件调用回调委托，并重复该过程。

完成记录事件后，调用 CloseAndSaveToFileAsync 以获取自最后一个日志文件以来的最后一个日志文件（如果尚未达到容量）可能仍处于打开状态。 还可以使用 CloseAndSaveToFileAsync 关闭会话并获取对最后一个日志文件的访问权限。 请注意，如果最后一个日志文件为空，或者 LogFileGenerated 方法已报告所有日志文件， 则 CloseAndSaveToFileAsync 方法将返回 null。

日志文件在 ApplicationData\Logs 文件夹中创建。

每个日志文件的名称基于会话的名称和索引。 每次创建新会话时，都会重置索引。 每当日志文件达到最大大小时，都会关闭它，索引递增，并使用新索引打开一个新的日志文件。 (因此，每次重启应用时，它都会开始覆盖 app 的上一个实例生成的日志文件。)

可以为 LogFileGenerated 事件添加处理程序，以便在每次关闭日志文件时通知应用。

如果不使用 LogFileGenerated 事件或 CloseAndSaveToFileAsync 方法， 则 FileLoggingSession 不会删除过时的日志文件 (尽管新会话可能会覆盖以前会话) 生成的文件。 应用负责根据需要查找和清理日志文件。

在通过 LogFileGenerated 事件或 CloseAndSaveToFileAsync 方法将日志文件提供给应用之前，该日志文件将重命名为特殊日志文件名。 始终使用相同的日志文件名，因此新日志将覆盖旧日志。 这样， LogFileGenerated 事件和 CloseAndSaveToFileAsync 方法有助于防止过时日志文件浪费 ApplicationData 文件夹中的空间。

当当前日志文件达到 256KB 时，FileLoggingSession 将关闭当前日志文件并启动新的日志文件。

构造函数

FileLoggingSession(String)

初始化 FileLoggingSession 类的新实例。

属性

Name	获取日志记录会话的名称。

方法

AddLoggingChannel(ILoggingChannel)	将日志记录通道添加到当前日志记录会话。
AddLoggingChannel(ILoggingChannel, LoggingLevel)	将日志记录通道添加到当前日志记录会话。 日志记录通道仅接受日志记录级别为或高于指定日志记录级别的事件。
Close()	结束当前日志记录会话。
CloseAndSaveToFileAsync()	结束当前日志记录会话并将其保存到文件中。
Dispose()	执行与释放或重置非托管资源关联的应用程序定义的任务。
RemoveLoggingChannel(ILoggingChannel)	从当前日志记录会话中删除指定的日志记录通道。

事件

LogFileGenerated

保存日志文件时引发。

另请参阅

• LoggingChannel
• IFileLoggingSession
• IClosable
• 日志记录示例 (Windows 10)