TraceWPP task

The Windows Driver Kit (WDK) provides the TraceWPP task so that you can run the tracewpp.exe tool when you build your driver using MSBuild. The tracewpp.exe tool is used to implement WPP Software Tracing.

WppEnabled is a new metadata for the ClCompile item that enables tracing for source files. The Wpp task runs through the entire ClCompile Item Collections and invokes tracewpp.exe for each Item for which the WppEnabled metadata is set to TRUE.

The WppEnabled metadata was added to the ClCompile Item because the WPP task runs on the same type of input files as the CL task, in this case .c, .cpp, and .h files.

Note You access the Item metadata for tracewpp by using the ClCompile item in project files. MSBuild uses the TraceWpp item internally inside the target to pass it to the task.

The following example shows how to edit the metadata in the .vcxproj file.

    <ClCompile Include="a.c" />
    <ClCompile Include="b.c">
    <ClCompile Include="test1.c" />
    <ClCompile Include="test2.c">

The command-line invocation would be:

tracewpp.exe  km /Ic:\test\b.c
tracewpp.exe  dll test2.c

The example above shows that MSBuild invokes tracewpp.exe only on b.c and test2.c because the WppEnabled metadata is set to TRUE for these inputs. Also note that the metadata for these two inputs are different. Therefore, the switches will also be different for these inputs. In other words, you can call each input with its own set of metadata.

WPP Task Parameter Item Metadata Tool Switch

Required ITaskItem[] parameter. Specifies a list of source files.


Optional string parameter. Specifies an alternate friendly name for the message GUID for messages that come from this trace provider.

%(TraceWpp.WppAddAlternateNameToMessageGUID) -o:String

Optional string parameter. Specifies an additional configuration file. WPP uses the specified file in addition to the default file, defaultwpp.ini.

%(TraceWpp.WppAdditionalConfigurationFile) -ini:Path

Optional string[] parameter. Adds a directory to the list of directories that WPP searches for include files.

%(TraceWpp.WppAdditionalIncludeDirectories) -I

Optional string parameter. Specifies an alternative configuration file. WPP uses this file instead of the defaultwpp.ini file.

%(TraceWpp.WppAlternateConfigurationFile) -defwpp:Path

Optional string parameter. For every source file that WPP processes with the name specified between the braces {}, WPP creates another file with the specified file name extension.

%(TraceWpp.WppGenerateUsingTemplateFile) -gen{File.tpl}*.ext

Optional Boolean parameter. If the value is TRUE, WPP performs a tracked incremental build. Otherwise, WPP performs a rebuild.


Optional int parameter. Establishes a numeric base for the numbering of format strings.

%(TraceWpp.WppNumericBaseForFormatStrings) -argbase:Number

Optional string parameter. Defines a WPP_CONTROL_GUIDS macro with the specified control GUID and WPP_DEFINE_BIT entries named 'Error', 'Unusual', and 'Noise'.

%(TraceWpp.WppAddControlGUID) -ctl:GUID

Optional string parameter. A list of command-line options.


Optional string[] parameter. Specifies the location of configuration and template files.

%(TraceWpp.WppConfigurationDirectories) -cfgdir:[Path]

Optional Boolean parameter. Defines the WPP_DLL macro.

%(TraceWpp.WppDllMacro) -dll

Optional string[] parameter. Specifies the file types that WPP recognizes as source files. WPP ignores files with a different file name extension.

%(TraceWpp.WppFileExtensions) -ext:.ext1 [.ext2]

Optional Boolean parameter. Directs WPP to ignore exclamation marks, also known as 'shrieks,' used in complex formatting, such as %!timestamp!%.

%(TraceWpp.WppIgnoreExclamationmarks) -noshrieks

Optional Boolean parameter. Defines the WPP_KERNEL_MODE macro, which traces kernel-mode components. By default, only user-mode components are traced.

%(TraceWpp.WppKernelMode) -km

Optional string parameter. Specifies the directory for the output files that WPP creates.

%(TraceWpp.WppOutputDirectory) -odir:Path

Optional string[] parameter. Defines a preprocessing symbol for your source file.

%(TraceWpp.WppPreprocessorDefinitions) /D

Optional string[] parameter. Preserves the specified file name extensions when creating TMH files.

%(TraceWpp.WppPreserveExtensions) -preserveext:ext1[,ext2]

Optional string parameter. Searches for configuration data, such as custom data types, in a file that is not a configuration file, as well as in defaultwpp.ini.

%(TraceWpp.WppScanConfigurationData) -scan:File

Optional string parameter. Directs WPP to search the source files for the specified string to initiate tracing.

%(TraceWpp.WppSearchString) -lookfor:String

Optional string parameter. Allows you to specify the full path to the folder where the tool is located.


Optional string[] parameter. Specifies functions that can then be used to generate trace messages.

%(TraceWpp.WppTraceFunction) -func:FunctionDescription

Optional string parameter. Log directory for tracker to write tlogs.


Optional Boolean parameter. If true, tracks file access patterns for this task.


Related topics

WPP Preprocessor

WPP Software Tracing

Send comments about this topic to Microsoft