WPP-Präprozessor

Artikel
06/15/2023

In diesem Abschnitt wird der Windows Software Trace-Präprozessor beschrieben, der allgemein als WPP-Präprozessor bezeichnet wird.

Aufrufen des WPP-Präprozessors

Sie können den WPP-Präprozessor mit Visual Studio und der MSBuild-Umgebung aufrufen.

So rufen Sie den WPP-Präprozessor auf

Klicken Sie mit der rechten Maustaste auf das Treiberprojekt in Projektmappen Explorer, und klicken Sie dann auf Eigenschaften.
Klicken Sie auf der Projekteigenschaftenseite auf Konfigurationseigenschaften, und klicken Sie auf WPP-Ablaufverfolgung.
Legen Sie unter Allgemein die Option WPP ausführen auf Ja fest.
Unter Befehlszeile können Sie unten Optionen hinzufügen, um das Ablaufverfolgungsverhalten anzupassen.

Beispielsweise können Sie unter WPP-Ablaufverfolgung eine einzelne Scankonfigurationsdatendatei angeben.

Wenn Sie mehr als eine Konfigurationsdatei angeben müssen, verweisen Sie in der Befehlszeile mithilfe der Option -scan auf Ihre Datei, damit instance benutzerdefinierte Datentypen angeben kann, z. B.:
```
-scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
```

Weitere Informationen zum Buildprozess finden Sie unter TraceWPP-Aufgabe und WDK- und Visual Studio-Buildumgebung.

Sie können den Präprozessor auch getrennt von der Buildumgebung ausführen, indem Sie das TraceWPP-Tool (TraceWPP.exe) verwenden. Dieses Tool befindet sich im Unterverzeichnis bin/x86 des WDK.

Allgemeine Optionen für die WPP-Ablaufverfolgung

In den folgenden Tabellen werden die Optionen für den WPP-Präprozessor beschrieben. Sie können diese Optionen in Visual Studio über die Eigenschaftenseite WPP-Ablaufverfolgung für Ihr Projekt oder als Parameter für das TraceWPP-Tool konfigurieren.

WPP-Ablaufverfolgungsoption	BESCHREIBUNG
Ausführen von WPP	Wenn true, ruft WPP auf.
Aktivieren der minimalen Neuerstellung	Wenn true, wird ein nachverfolgter inkrementeller Build ausgeführt. wenn false, wird eine neuerstellung ausgeführt.

Funktions- und Makrooptionen

WPP-Ablaufverfolgungsoption	TraceWPP-Befehlsoption	BESCHREIBUNG
Präprozessordefinitionen	-DMakro	Fügt am Anfang der generierten Datei #define Makro hinzu, wobei Makro der Name eines Makros ist. Diese Option hat die gleiche Auswirkung wie die Compileroption /D (Definieren eines Makros). Sie ist enthalten, um sicherzustellen, dass definierten Dateien am Anfang der TMH-Dateien gültig sind.
	-DMakroerweiterung=	Fügt #defineMakroerweiterung am Anfang der generierten Datei hinzu, wobei Makro der Name eines Makros und Erweiterung der erweiterte Wert ist. Diese Option hat die gleiche Auswirkung wie die Compileroption /D (Definieren eines Makros). Sie ist enthalten, um sicherzustellen, dass definierten Dateien am Anfang der TMH-Dateien gültig sind.
Ablaufverfolgung Kernel-Mode Komponenten	-Km	Definiert das WPP_KERNEL_MODE Makros, das Kernelmoduskomponenten verfolgt. Standardmäßig werden nur Komponenten im Benutzermodus nachverfolgt.
Dll-Makro aktivieren	-Dll	Definiert das WPP_DLL-Makros, das dazu führt, dass die WPP-Datenstrukturen bei jedem Aufruf WPP_INIT_TRACING initialisiert werden. Andernfalls werden die Strukturen nur einmal initialisiert.
Angeben der Steuerelement-GUID	-ctl:GUID	Definiert ein WPP_CONTROL_GUIDS Makro mit der angegebenen Steuerelement-GUID und WPP_DEFINE_BIT Einträgen mit den Namen Fehler, Ungewöhnlich und Rauschen. Dies ist eine Alternative zum Hinzufügen des Makros zur Quelldatei. GUID stellt die Steuerelement-GUID dar.

Such- und Formatierungsoptionen

WPP-Ablaufverfolgungsoption	TraceWPP-Befehlsoption	BESCHREIBUNG
Ausrufezeichen ignorieren	-noshrieks	Weist WPP an, Ausrufezeichen zu ignorieren, die auch als "Shrieks" bezeichnet werden. Wird in komplexen Formatierungen verwendet, z. B. %!timestamp!%. Standardmäßig sind Ausrufezeichen erforderlich, und WPP versucht, sie zu interpretieren.
Numerische Basis für die Nummerierung von Formatzeichenfolgen	-argbase:Zahl	Erstellt eine numerische Basis für die Nummerierung von Formatzeichenfolgen, z. B. "%1!d!, %2!s!". Der Standardwert ist 1.
Funktion zum Generieren von Ablaufverfolgungsmeldungen	-func:FunctionDescription	Gibt Alternativen zum DoTraceMessage-Makro an. Diese Funktionen können dann zum Generieren von Ablaufverfolgungsmeldungen verwendet werden. Sie können beispielsweise eine Funktion definieren, die sowohl die Flags als auch die Ebene für eine Ablaufverfolgungsnachricht angibt, z. B.: `-func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...)` Sie können mehrere Instanzen der Option -func verwenden. Diese Option ist eine Alternative zum Angeben von Funktionsbeschreibungen in einer lokalen Konfigurationsdatei.
Geben Sie die zu suchende Zeichenfolge an.	-lookfor:String	Weist WPP an, die Quelldateien nach der angegebenen Zeichenfolge zu durchsuchen, um die Ablaufverfolgung zu initiieren. Standardmäßig sucht WPP nach der Zeichenfolge "WPP_INIT_TRACING". Dies ist eine erweiterte Option für Benutzer, die ihre eigenen Vorlagen schreiben. Beispiel: in default.tpl: `IF FOUND WPP_INIT_TRACING INCLUDE um-init.tpl ENDIF`
Modulname angeben	-p:String	Gibt einen alternativen Anzeigenamen für die Nachrichten-GUID von Nachrichten von diesem Ablaufverfolgungsanbieter an. Standardmäßig ist der Anzeigename der Nachrichten-GUID der Name des Verzeichnisses, in dem der Ablaufverfolgungsanbieter erstellt wurde. Der Anzeigename der Nachrichten-GUID wird standardmäßig im Präfix der Ablaufverfolgungsnachricht angezeigt, das durch die Variable %1 dargestellt wird. Mit diesem Parameter können Sie dem Präfix eine Zeichenfolge hinzufügen, die dem Benutzer hilft, den Ablaufverfolgungsanbieter zu identifizieren, z. B. den Anzeigenamen des Ablaufverfolgungsanbieters, den Namen des Moduls, das den Ablaufverfolgungsanbieter enthält, oder den Namen eines Projekts, das durch das Erstellen mehrerer Ablaufverfolgungsanbieter implementiert wird. Diese Informationen helfen Benutzern, verwandte Ablaufverfolgungsanbieter zuzuordnen, die sich in verschiedenen Dateien oder unterschiedlichen Pfaden befinden. Der -p-Parameter erfordert die Version von WPP, die im Windows Driver Kit (WDK) für Windows Vista und höhere Versionen des WDK enthalten ist. Der -p-Parameter funktioniert unter Windows 2000 und höheren Versionen von Windows. Beispiele: `-p:TraceDrv -p:AudioModule`

Dateioptionen

WPP-Ablaufverfolgungsoption	TraceWPP-Befehlsoption	BESCHREIBUNG
Zusätzliche Includeverzeichnisse	-IPath1[;Path2]	Gibt mindestens ein Verzeichnis an, das dem include-Pfad hinzugefügt werden soll. Verwenden Sie Semikolons als Trennzeichen, wenn mehrere Verzeichnisse vorhanden sind. Identisch mit -cfgdir.
Konfigurationsverzeichnisse	-cfgdir:Path1[;Path2]	Gibt den Speicherort von Konfigurations- und Vorlagendateien an. Path1 und Path2 stellen den vollqualifizierten Pfad zu einem Verzeichnis dar. Sie können mehrere Pfade angeben. Der Standardwert ist das lokale Verzeichnis.
Dateierweiterungen	-Extern:.ext1[.ext2]	Gibt die Dateitypen an, die WPP als Quelldateien erkennt. WPP ignoriert Dateien mit einer anderen Dateinamenerweiterung. Standardmäßig erkennt WPP nur C-, C++-, CPP- und CXX-Dateien. Mit dieser Option können Sie die Standardeinstellungen für WPP verwenden, ohne Ressourcendateien löschen oder umbenennen zu müssen, die von WPP nicht verwendet werden, z. B. RC- und MC-Dateien. Um z. B. die Ablaufverfolgung zu C++-Dateien und Headerdateien (.h) hinzuzufügen, verwenden Sie den folgenden Befehl: -ext:.cpp. CPP.h.H Verwenden Sie auch die Option -preserveext , um den TMH-Dateien für die C++- und Headerdateien einen anderen Namen zuzuweisen.
Beibehalten von Dateierweiterungen	-preserveext:.ext1[.ext2]	Behält die angegebenen Dateinamenerweiterungen beim Erstellen von TMH-Dateien bei. Standardmäßig haben TMH-Dateien für alle Dateitypen den Namen filename.tmh. Dies führte zu Dateinamenkonflikten, wenn Sie über mehrere Quelldateien mit demselben Namen verfügen. Beispielsweise werden TMH-Dateien für C-Dateien (.c) und Headerdateien (.h) standardmäßig mit dem Namen filename.tmh> bezeichnet<. Mithilfe von -preserveext:.c .h werden die TMH-Dateien mit dem Namen filename.c.tmh> und <filename.h.tmh> bezeichnet<.
Ausgabeverzeichnis	-odir:path	Gibt das Verzeichnis für die Ausgabedateien an, die von WPP erstellt werden. Path ist der vollqualifizierte Pfad zum Verzeichnis. Der Standardwert ist das lokale Verzeichnis.
Angeben der Vorlagendatei	-gen{ File.tpl }. ext	Erstellen Sie für jede Quelldatei, die WPP mit dem zwischen geschweiften Klammern {}angegebenen Namen verarbeitet, eine weitere Datei mit der angegebenen Dateinamenerweiterung. File.tpl stellt die Quelldatei dar. .ext stellt den Typ der erstellten Datei und deren Dateinamenerweiterung dar. Sie können mehrere -gen-Optionen* angeben. Beispielsweise bedeutet -gen{um-default.tpl}.tmh , dass für jede datei um-default.tpl , die WPP verarbeitet, eine um-default.tmh-Datei erzeugt wird.
Überprüfen von Konfigurationsdaten	-scan:File	Sucht nach Konfigurationsdaten, z. B. benutzerdefinierten Datentypen, in einer Datei, die keine Konfigurationsdatei ist, sowie in defaultwpp.ini. Platzieren Sie begin_wpp Konfiguration und end_wpp Zeichenfolgen um die Konfigurationsdaten, um sie zu identifizieren. Verwenden Sie das gleiche Format für die Konfigurationsdaten wie in defaultwpp.ini. Wenn Sie die Konfigurationsdaten zu einer benutzerdefinierten Konfigurationsdatei hinzugefügt haben, verwenden Sie den Parameter -ini .
Alternative Konfigurationsdatei	-defwpp:path	Gibt eine alternative Konfigurationsdatei an. Wpp verwendet diese Datei anstelle der defaultwpp.ini-Datei.
Zusätzliche Konfigurationsdatei	-ini:Path	Gibt eine zusätzliche Konfigurationsdatei an. WPP verwendet die angegebene Datei zusätzlich zur Standarddatei, defaultwpp.ini. Verwenden Sie diesen Parameter, wenn Sie eine neue Konfigurationsdatei erstellt haben, um Konfigurationsdaten für die Ablaufverfolgung zu speichern. Wenn Sie die Konfigurationsdaten zu einem anderen Dateityp hinzugefügt haben, z. B. einer Quell- oder Headerdatei, verwenden Sie den Parameter -scan .

WPP-Buildprozess

Wenn WPP für eine Treiber- oder Benutzermodusanwendung aktiviert ist, wird beim Erstellen des Treibers oder der Anwendung der WPP-Präprozessor aufgerufen, bevor der Treiber oder die Anwendungsdateien kompiliert werden.

Der WPP-Buildprozess führt die folgenden Schritte aus:

Der WPP-Präprozessor verarbeitet WPP-Makros in jeder Quelldatei und erstellt für jede Quelldatei eine Headerdatei für Ablaufverfolgungsmeldungen . Der Quellcode wird nicht direkt geändert.
Nachdem der WPP-Präprozessor die Headerdateien der Ablaufverfolgungsnachricht erstellt hat, verarbeitet der C-Präprozessor die integrierten WPP-Makros in den Headerdateien der Ablaufverfolgungsnachricht auf normale Weise.

Freigeben über