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.

<ItemGroup>
    <ClCompile Include="a.c" />
      <WppEnabled>false</WppEnabled>
    <ClCompile Include="b.c">
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppAdditionalIncludeDirectories>c:\test\</WppAdditionalIncludeDirectories>
    </ClCompile>
    <ClCompile Include="test1.c" />
    <ClCompile Include="test2.c">
        <WppEnabled>true</WppEnabled>
        <WppDllMacro>true</WppDllMacro>
    </ClCompile>
</ItemGroup>

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
Sources Required ITaskItem[] parameter. Specifies a list of source files.	@(TraceWpp)
AddAlternateNameToMessageGUID Optional string parameter. Specifies an alternate friendly name for the message GUID for messages that come from this trace provider.	%(TraceWpp.WppAddAlternateNameToMessageGUID)	-o:String
AdditionalConfigurationFile 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
AdditionalIncludeDirectories Optional string[] parameter. Adds a directory to the list of directories that WPP searches for include files.	%(TraceWpp.WppAdditionalIncludeDirectories)	-I
AlternateConfigurationFile Optional string parameter. Specifies an alternative configuration file. WPP uses this file instead of the defaultwpp.ini file.	%(TraceWpp.WppAlternateConfigurationFile)	-defwpp:Path
GenerateUsingTemplateFile 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
MinimalRebuildFromTracking Optional Boolean parameter. If the value is TRUE, WPP performs a tracked incremental build. Otherwise, WPP performs a rebuild.	%(TraceWpp.WppMinimalRebuildFromTracking)
NumericBaseForFormatStrings Optional int parameter. Establishes a numeric base for the numbering of format strings.	%(TraceWpp.WppNumericBaseForFormatStrings)	-argbase:Number
AddControlGUID 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
AdditionalOptions Optional string parameter. A list of command-line options.	%(TraceWpp.WppAdditionalOptions)
ConfigurationDirectories Optional string[] parameter. Specifies the location of configuration and template files.	%(TraceWpp.WppConfigurationDirectories)	-cfgdir:[Path]
DllMacro Optional Boolean parameter. Defines the WPP_DLL macro.	%(TraceWpp.WppDllMacro)	-dll
FileExtensions 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]
IgnoreExclamationmarks Optional Boolean parameter. Directs WPP to ignore exclamation marks, also known as 'shrieks,' used in complex formatting, such as %!timestamp!%.	%(TraceWpp.WppIgnoreExclamationmarks)	-noshrieks
KernelMode 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
OutputDirectory Optional string parameter. Specifies the directory for the output files that WPP creates.	%(TraceWpp.WppOutputDirectory)	-odir:Path
PreprocessorDefinitions Optional string[] parameter. Defines a preprocessing symbol for your source file.	%(TraceWpp.WppPreprocessorDefinitions)	/D
PreserveExtensions Optional string[] parameter. Preserves the specified file name extensions when creating TMH files.	%(TraceWpp.WppPreserveExtensions)	-preserveext:ext1[,ext2]
ScanConfigurationData 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
SearchString Optional string parameter. Directs WPP to search the source files for the specified string to initiate tracing.	%(TraceWpp.WppSearchString)	-lookfor:String
ToolPath Optional string parameter. Allows you to specify the full path to the folder where the tool is located.	$(WPPToolPath)
TraceFunction Optional string[] parameter. Specifies functions that can then be used to generate trace messages.	%(TraceWpp.WppTraceFunction)	-func:FunctionDescription
TrackerLogDirectory Optional string parameter. Log directory for tracker to write tlogs.	%(TraceWpp.WppTrackerLogDirectory)
TrackFileAccess Optional Boolean parameter. If true, tracks file access patterns for this task.	$(TrackFileAccess)

Related topics

WPP Preprocessor

WPP Software Tracing