TraceLoggingChannel 宏 (traceloggingprovider.h)

  • 项目

TraceLogging 包装器宏 ，用于设置事件的通道。

大多数 TraceLogging 事件不需要更改事件的默认通道，也不应使用 TraceLoggingChannel。

语法

void TraceLoggingChannel(
  [in]  eventChannel
);

参数

[in] eventChannel

事件应记录到的通道。 这是一个介于 0 到 255 的整数值。

有关事件通道的详细信息，请参阅 EVENT_DESCRIPTOR 。

返回值

无

备注

TraceLoggingChannel(eventChannel) 可用作 TraceLoggingWrite 宏调用的参数。 大多数 TraceLogging 事件不需要更改事件的默认通道，也不应使用 TraceLoggingChannel。

eventChannel 参数必须是编译时常量 0 到 255。 如果未 TraceLoggingChannel(n) 提供参数，则默认通道为 11 (WINEVENT_CHANNEL_TRACELOGGING) ，表示这是正常的 TraceLogging 事件。 如果提供了多个 TraceLoggingChannel(n) 参数，将使用最后一个 TraceLoggingChannel(n) 参数中的值。

通道用于 Windows (ETW) 方案的高级事件跟踪。 其中包括写入系统定义的事件使用者，例如 Windows 事件日志。

警告

如果提供程序将在早于 Windows 10 的 Windows 上运行，请不要使用 TraceLoggingChannel。 若要使事件解码器识别为 TraceLogging 兼容事件，必须将通道设置为默认值 (11) 或者必须在 EventWrite 期间由 ETW 运行时将其标记为 TraceLogging 事件。 通过调用 EventSetInformation 将提供程序配置为 TraceLogging 提供程序来启用此事件标记。 Windows 10 或更高版本中的 EventSetInformation 支持 TraceLogging 事件，而不考虑通道，但早期版本的 Windows 需要更新才能支持标记 TraceLogging 事件。 对于在未更新 EventSetInformation 的系统上捕获的事件，通道 11 是识别 TraceLogging 事件的唯一方法，因此具有其他通道的事件可能无法正确解码。

TraceLogging 和事件日志

在大多数情况下，开发人员将基于清单的 ETW 用于需要由事件日志记录的事件。 事件日志主要用于收集可能对系统管理员有用的低容量事件。 基于清单的 ETW 非常适合此情况，因为它支持精心策划的事件， (组件的所有事件都在一个清单文件) 中描述，并且它支持可本地化的消息字符串，可帮助管理员了解如何对事件做出反应。

尽管 TraceLogging 事件没有消息字符串，并且通常不是集中策展的，但 TraceLogging 仍适用于某些事件日志方案。 例如，虽然转到 Windows 日志 (应用程序、安全性、安装程序和系统) 的事件应始终具有本地化的消息字符串，并且应始终对系统管理员有用，但应用程序和服务日志中记录的事件可能更具技术性，并且可以记录诊断信息。 写入应用程序和服务日志时，可能需要使用 TraceLogging 来简化记录事件的管理。

将 TraceLogging 事件与 Windows 事件日志配合使用类似于将基于常规清单的事件与事件日志配合使用。 仍需要创建并注册清单来定义提供程序和通道，但不需要在清单中定义各个事件：

  • 编写定义提供程序和事件日志通道的 ETW 清单。 清单中的提供程序应使用与在 TRACELOGGING_DEFINE_PROVIDER 宏中使用的相同提供程序名称和提供程序 guid (提供程序 ID ) 。 清单不需要包含 <event> 或 <template> 定义，因为 TraceLogging 事件是自我描述的。
  • 在组件的生成过程中，使用 Windows SDK 10.0.22621 或更高版本的消息编译器 (MC.exe) 编译清单。 这将生成以下文件：
    • ManifestName.h：包含常量定义的 C/C++ 标头。 这将定义 ChannelSymbol 以及需要在 TraceLogging 事件中使用的 ChannelSymbol_KEYWORD 常量。 (每个通道的常量的实际名称将有所不同。)
    • ManifestName.rc： 资源编译器 (RC.exe) 脚本，用于将清单 BIN 数据添加到二进制 (EXE、DLL 或 SYS) 文件。 需要将此资源脚本包含在组件中某个二进制文件的资源中。
    • ManifestNameTEMP.BIN， MSG00001.bin：由 引用的 ManifestName.rc清单 BIN 数据。
  • #include 生成的 ManifestName.h 文件到需要生成 TraceLogging 事件的代码中。 这将定义 ChannelSymbol 并 ChannelSymbol_KEYWORD 常量。
    • 如果在清单中的 或 <importChannel> 定义上<channel>指定了 symbol 属性，则 ChannelSymbol 的名称将是符号属性的值。 否则，ChannelSymbol 将ProviderSymbol_CHANNEL_ChannelName (即，它将使用元素中的符号<provider>和或 元素) 的名称<channel><importChannel>。
    • ChannelSymbol_KEYWORD的名称是 ChannelSymbol 的名称，_KEYWORD后跟 。
    • ChannelSymbol_KEYWORD常量仅由 MC.exe 10.0.22621 或更高版本生成。
  • 要转到事件日志的每个 TraceLogging 事件都必须使用TraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD)设置事件的通道和关键字 (keyword) 。 例如，如果通道的符号为 MY_CHANNEL，我会将 作为参数TraceLoggingWrite添加到TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD)事件的宏中。
  • 为了使事件日志能够识别提供程序，清单中的信息 必须包含在模块的资源中 ， (将安装在目标系统上的 DLL、EXE 或 SYS 文件) 。
  • 为了使事件日志从提供程序接收事件，必须在组件安装期间使用 wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll 在目标系统上注册清单。 还必须在组件卸载期间使用 wevtutil um ManifestFile.man 取消注册清单。

重要

如果提供程序已注册到事件日志，则提供程序生成的所有事件都必须具有由 TraceLoggingKeyword 指定的非零关键字 (keyword) ，即使该事件不适用于事件日志也是如此。 无法有效地筛选关键字 (keyword) 0 的事件，并且将仅传递到事件日志以丢弃。 如果事件日志正在侦听来自提供程序的任何事件，则关键字为 0 的任何事件都会不必要地增加事件日志开销。

事件日志的 TraceLogging 事件示例：

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

在适当的情况下，可以通过使用多个 TraceLoggingKeyword 参数或在单个 TraceLoggingKeyword 参数中指定多个关键字（例如 TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD)）将其他用户指定的关键字添加到事件中。

要求

要求 值
最低受支持的客户端 Windows 10 [仅限桌面应用]
最低受支持的服务器 Windows Server 2012 R2
目标平台 Windows
标头 traceloggingprovider.h

另请参阅

EVENT_DESCRIPTOR

TraceLoggingWrite

TraceLogging 包装宏