Redigera

Dela via


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)

WPP Preprocessor

WPP Software Tracing