WPP 预处理器
本部分介绍 Windows 软件跟踪预处理器，通常称为 WPP 预处理器。
调用 WPP 预处理器
可以使用 Visual Studio 和 MSBuild 环境调用 WPP 预处理器。
调用 WPP 预处理器
在解决方案资源管理器中右键单击驱动程序项目，然后单击“ 属性”。
在项目属性页中，单击“配置属性”，然后单击“WPP 跟踪”
在“常规”下，将“运行 WPP”选项设置为“是”。
在命令行下，可以添加以下选项来自定义跟踪行为。
例如，在 WPP 跟踪下，可以指定单个扫描配置文件。
如果需要提供多个配置文件（例如指定自定义数据类型），请使用 -scan 选项在命令行中引用文件，例如：
-scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
有关生成过程的详细信息，请参阅 TraceWPP 任务 和 WDK 和 Visual Studio 生成环境。
还可以使用 TraceWPP 工具（TraceWPP.exe）独立于生成环境运行预处理器。 此工具位于 WDK 的 bin/x86 子目录中。
WPP 跟踪常规选项
下表描述了 WPP 预处理器的选项。 可以使用项目的 WPP 跟踪属性页在 Visual Studio 中配置这些选项，也可以将其用作 TraceWPP 工具的参数。
| WPP 跟踪选项 | 说明 |
|---|---|
运行 WPP |
如果为 true，则调用 WPP。 |
启用最小重新生成 |
如果为 true，则执行跟踪的增量生成;如果为 false，则执行重新生成。 |
函数和宏选项
| WPP 跟踪选项 | TraceWPP 命令选项 | 说明 |
|---|---|---|
预处理器定义 |
-D宏 |
将 #define 宏添加到生成的文件的开头，其中宏是宏的名称。 此选项的效果与 /D （定义宏）编译器选项的效果相同。 它包含在内，以确保定义在 TMH 文件的开头有效。 |
-D宏=扩展 |
将 #define 宏扩展添加到生成的文件的开头，其中宏是宏的名称，“扩展”是展开的值。 此选项的效果与 /D （定义宏）编译器选项的效果相同。 它包含在内，以确保定义在 TMH 文件的开头有效。 |
|
跟踪内核模式组件 |
-公里 |
定义跟踪内核模式组件的WPP_KERNEL_MODE宏。 默认情况下，仅跟踪用户模式组件。 |
启用 Dll 宏 |
-dll |
定义WPP_DLL宏，每当调用WPP_INIT_TRACING时，都会初始化 WPP 数据结构。 否则，结构仅初始化一次。 |
指定控件 GUID |
-ctl： GUID |
使用指定的控件 GUID 和名为 Error、Unusual 和 Noise 的WPP_DEFINE_BIT项定义WPP_CONTROL_GUIDS宏。
这是将宏添加到源文件的替代方法。 GUID 表示控件 GUID。 |
搜索和格式设置选项
| WPP 跟踪选项 | TraceWPP 命令选项 | 说明 |
|---|---|---|
忽略感叹号 |
-noshrieks |
指示 WPP 忽略感叹号，也称为“尖叫声”。 用于复杂格式，如 %！timestamp！%。 默认情况下，需要感叹号，WPP 会尝试解释它们。 |
格式字符串编号的数字基数 |
-argbase： Number |
为格式字符串编号（如“%1！d！，%2！s！”）建立数字基数。 默认值为 1。 |
用于生成跟踪消息的函数 |
-func： FunctionDescription |
指定 DoTraceMessage 宏的替代项。 然后，可以使用这些函数生成跟踪消息。 例如，可以定义一个函数，该函数指定跟踪消息的标志和级别，例如： 可以使用 -func 选项的多个实例。 此选项是在本地配置文件中指定函数说明的替代方法。 |
指定要搜索的字符串 |
-lookfor：String |
指示 WPP 在源文件中搜索指定字符串以启动跟踪。 默认情况下，WPP 搜索字符串“WPP_INIT_TRACING”。 对于正在编写自己的模板的用户，这是一个高级选项。 例如，在 default.tpl 中： |
指定模块名称 |
-p： 字符串 |
指定来自此跟踪提供程序的消息的消息 GUID 的备用友好名称。 默认情况下，消息 GUID 的友好名称是生成跟踪提供程序的目录的名称。 默认情况下，消息 GUID 的友好名称显示在变量 %1 所表示的跟踪消息前缀中。 可以使用此参数将字符串添加到前缀，帮助用户标识跟踪提供程序，例如跟踪提供程序的友好名称、包含跟踪提供程序的模块的名称，或通过创建多个跟踪提供程序实现的项目的名称。 此信息可帮助用户关联位于不同文件或不同路径中的相关跟踪提供程序。 -p 参数需要 Windows Vista 和 WDK 更高版本 Windows 驱动程序工具包（WDK）中包含的 WPP 版本。 -p 参数适用于 Windows 2000 及更高版本的 Windows。 示例： |
文件选项
| WPP 跟踪选项 | TraceWPP 命令选项 | 说明 |
|---|---|---|
附加包含目录 |
-I Path1[;Path2] |
指定一个或多个要添加到包含路径中的目录；存在多个目录时，请用分号分隔。 与 -cfgdir 相同。 |
配置目录 |
-cfgdir： Path1[;Path2] |
指定配置和模板文件的位置。 Path1 和 Path2 表示目录的完全限定路径。 可以指定多个路径。 默认值为本地目录。 |
文件扩展名 |
-内线：。ext1 [.ext2] |
指定 WPP 识别为源文件的文件类型。 WPP 忽略文件扩展名不同的文件。 默认情况下，WPP 仅识别 .c、.c++、.cpp 和 .cxx 文件。 此选项允许使用 WPP 的默认设置，而无需删除或重命名 WPP 不使用的资源文件，例如 .rc 和 .mc 文件。 例如，若要将跟踪添加到C++文件和标头 （.h） 文件，请使用以下命令： -ext:.cpp。CPP.h.H 此外，若要为C++和头文件提供不同的名称的 TMH 文件，请使用 -preserveext 选项。 |
保留文件扩展名 |
-preserveext： .ext1[.ext2] |
创建 TMH 文件时保留指定的文件扩展名。 默认情况下，所有文件类型的 TMH 文件都命名为 filename.tmh。 如果有多个具有相同名称的源文件，则会导致文件名冲突。 例如，默认情况下，C 文件 （.c） 和标头 （.h） 文件的 TMH 文件将命名为 <filename.tmh>。 通过使用 -preserveext：.c .h，TMH 文件名为 <filename.c.tmh> 和 <filename.h.tmh>。 |
输出目录 |
-odir： path | 指定 WPP 创建的输出文件的目录。 路径 是目录的完全限定路径。 默认值为本地目录。 |
指定模板文件 |
-gen{ File.tpl }. ext |
对于 WPP 使用大括号 {}之间指定的名称处理的每个源文件，请创建具有指定文件扩展名的另一个文件。 File.tpl 表示源文件。 *.ext 表示创建的文件类型及其文件扩展名。 可以指定多个 -gen 选项。 例如， -gen{um-default.tpl}.tmh 表示对于 WPP 处理的每个 um-default.tpl 文件，它生成 um-default.tmh 文件。 |
扫描配置数据 |
-scan：File |
在不是配置文件的文件以及defaultwpp.ini中搜索配置数据，例如自定义数据类型。 将begin_wpp配置和end_wpp字符串放在配置数据周围以标识它。 对配置数据使用的格式与defaultwpp.ini中使用的格式相同。 如果将配置数据添加到自定义配置文件，请使用 -ini 参数。 |
备用配置文件 |
-defwpp：path |
指定备用配置文件。 Wpp 使用此文件而不是defaultwpp.ini文件。 |
其他配置文件 |
-ini：Path |
指定其他配置文件。 WPP 除了默认文件之外，WPP 还使用指定的文件，defaultwpp.ini。 创建新的配置文件以存储用于跟踪的配置数据时，请使用此参数。 如果已将配置数据添加到其他类型的文件（如源或头文件），请使用 -scan 参数。 |
WPP 生成过程
如果为驱动程序或用户模式应用程序启用了 WPP，则生成驱动程序或应用程序将在编译驱动程序或应用程序文件之前调用 WPP 预处理器。
WPP 生成过程完成以下步骤：
WPP 预处理器处理每个源文件中的 WPP 宏，并为每个源文件创建 跟踪消息头文件 。 不会直接修改源代码。
WPP 预处理器创建跟踪消息头文件后，C 预处理器以正常方式处理跟踪消息头文件中的内置 WPP 宏。