WPP Preprocessor

In deze sectie wordt de Windows Software Trace Preprocessor beschreven, ook wel bekend als de WPP-preprocessor.

De WPP-preprocessor aanroepen

U kunt de WPP-preprocessor aanroepen met behulp van Visual Studio en de MSBuild-omgeving.

De WPP-preprocessor aanroepen

1. Klik met de rechtermuisknop op het stuurprogrammaproject in Solutions Explorer en klik op Eigenschappen.

2. Klik op de projecteigenschapspagina op Configuratie-eigenschappen en klik op WPP-tracering

3. Stel onder Algemeende optie WPP- uitvoeren in op Ja-.

4. Onder Opdrachtregel kunt u hieronder opties toevoegen om het traceringsgedrag aan te passen.

   U kunt bijvoorbeeld onder WPP-tracering één configuratiegegevensbestand voor scannen opgeven.

   Als u meer dan één configuratiebestand moet opgeven, bijvoorbeeld om aangepaste gegevenstypen op te geven, verwijst u naar het bestand in de opdrachtregel met behulp van de optie -scan , bijvoorbeeld:

   -scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
   

Zie TraceWPP-taak en WDK- en Visual Studio-buildomgeving voor meer informatie over het buildproces.

U kunt de preprocessor ook afzonderlijk van de build-omgeving uitvoeren met behulp van het hulpprogramma TraceWPP (TraceWPP.exe). Dit hulpprogramma bevindt zich in de submap bin/x86 van de WDK.

Algemene opties voor WPP-tracering

In de volgende tabellen worden de opties voor de WPP-preprocessor beschreven. U kunt deze opties in Visual Studio configureren met behulp van de eigenschappenpagina WPP Tracing voor uw project of als parameters voor het hulpprogramma TraceWPP.

WPP-traceringsoptie	Beschrijving
WPP uitvoeren	Als waar, roept u WPP aan.
Minimale herbouw inschakelen	Indien waar, wordt een bijgehouden incrementele build uitgevoerd; als dit onwaar is, wordt een herbouw uitgevoerd.

Opties voor functies en macro's

WPP-traceringsoptie	Opdrachtoptie TraceWPP	Beschrijving
Preprocessor-definities	-DMacro	Voegt #definemacro toe aan het begin van het gegenereerde bestand waarin Macro de naam van een macro is. Deze optie heeft hetzelfde effect als de compileroptie /D (een macro definiëren). Het is opgenomen om ervoor te zorgen dat de definities geldig zijn aan het begin van de TMH-bestanden.
	-Dmacro-uitbreiding=	Voegt #definemacro-uitbreiding toe aan het begin van het gegenereerde bestand waarin Macro de naam van een macro is en Uitbreiding de uitgevouwen waarde is. Deze optie heeft hetzelfde effect als de compileroptie /D (een macro definiëren). Het is opgenomen om ervoor te zorgen dat de definities geldig zijn aan het begin van de TMH-bestanden.
Traceren van onderdelen Kernel-Mode	-kilometer	Hiermee definieert u de WPP_KERNEL_MODE macro, die onderdelen van de kernelmodus traceert. Standaard worden alleen onderdelen van de gebruikersmodus getraceerd.
Dll-macro inschakelen	-Dll	Definieert de WPP_DLL macro, waardoor de WPP-gegevensstructuren worden geïnitialiseerd wanneer WPP_INIT_TRACING wordt aangeroepen. Anders worden de structuren slechts één keer geïnitialiseerd.
Besturings-GUID opgeven	-ctl:GUID	Definieert een WPP_CONTROL_GUIDS macro met de opgegeven besturingselement-GUID en WPP_DEFINE_BIT vermeldingen met de naam Error, Unusual en Noise. Dit is een alternatief voor het toevoegen van de macro aan het bronbestand. GUID vertegenwoordigt de besturingselement-GUID.

Opties voor zoeken en opmaak

WPP-traceringsoptie	Opdrachtoptie TraceWPP	Beschrijving
Uitroeptekens negeren	-noshrieks	Beveelt WPP om uitroeptekens te negeren, ook wel „shrieks” genoemd. Wordt gebruikt in complexe opmaak, zoals %!tijdstempel!%. Standaard zijn uitroeptekens vereist en probeert WPP deze te interpreteren.
Numerieke basis voor het nummeren van notatietekenreeksen	-argbase:Getal	Hiermee wordt een numerieke basis voor het nummeren van notatietekenreeksen gemaakt, zoals '%1!d!, %2!s!'. De standaardwaarde is 1.
Functie voor het genereren van traceringsberichten	-func:FunctionDescription	Geeft alternatieven voor de DoTraceMessage-macro op. Deze functies kunnen vervolgens worden gebruikt om traceringsberichten te genereren. U kunt bijvoorbeeld een functie definiëren waarmee zowel de vlaggen als het niveau voor een traceringsbericht worden opgegeven, zoals: -func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...) U kunt meerdere exemplaren van de optie -func gebruiken. Deze optie is een alternatief voor het opgeven van functiebeschrijvingen in een lokaal configuratiebestand.
Tekenreeks opgeven om naar te zoeken	-lookfor:String	Hiermee wordt WPP om de bronbestanden voor de opgegeven tekenreeks te doorzoeken om tracering te initiëren. Standaard zoekt WPP naar de tekenreeks 'WPP_INIT_TRACING'. Dit is een geavanceerde optie voor gebruikers die hun eigen sjablonen schrijven. Bijvoorbeeld in default.tpl: IF FOUND WPP_INIT_TRACING INCLUDE um-init.tpl ENDIF
Modulenaam opgeven	-p:Tekenreeks	Hiermee geeft u een alternatieve beschrijvende naam op voor de bericht-GUID van berichten van deze traceringsprovider. Standaard is de vriendelijke naam van de bericht-GUID de naam van de map waarin de traceringsprovider is gebouwd. De beschrijvende naam van de bericht-GUID verschijnt standaard in het traceringsberichtvoorvoegsel en wordt vertegenwoordigd door de variabele %1. U kunt deze parameter gebruiken om een tekenreeks toe te voegen aan het voorvoegsel waarmee de gebruiker de traceringsprovider kan identificeren, zoals de beschrijvende naam van de traceringsprovider, de naam van de module die de traceringsprovider bevat of de naam van een project dat wordt geïmplementeerd door verschillende traceringsproviders te maken. Deze informatie helpt gebruikers gerelateerde traceringsproviders te koppelen die zich in verschillende bestanden of verschillende paden bevinden. Voor de parameter -p is de versie van WPP vereist die is opgenomen in de Windows Driver Kit (WDK) voor Windows Vista en latere versies van de WDK. De parameter -p werkt in Windows 2000 en nieuwere versies van Windows. Voorbeelden: -p:TraceDrv -p:AudioModule

Bestandsopties

WPP-traceringsoptie	Opdrachtoptie TraceWPP	Beschrijving
Aanvullende inclusiemappen	-IPath1[;Pad2]	Specificeer een of meer directories om toe te voegen aan het insluitingspad; gescheiden door puntkomma's als er meer dan één is. Hetzelfde als -cfgdir.
Configuratiedirectories	-cfgdir:Path1[;Path2]	Hiermee geeft u de locatie van configuratie- en sjabloonbestanden. Path1 en Path2 vertegenwoordigen het volledig gekwalificeerde pad naar een map. U kunt meerdere paden opgeven. De standaardwaarde is de lokale map.
Bestandsextensies	-ext:.ext1[.ext2]	Hiermee geeft u de bestandstypen op die WPP herkent als bronbestanden. WPP negeert bestanden met een andere bestandsnaamextensie. Standaard herkent WPP alleen .c-, .c++-, .cpp- en .cxx-bestanden. Met deze optie kunt u de standaardinstellingen voor WPP gebruiken zonder resourcebestanden te verwijderen of de naam ervan te wijzigen die niet door WPP worden gebruikt, zoals RC- en MC-bestanden. Als u bijvoorbeeld tracering wilt toevoegen aan C++-bestanden en headerbestanden (.h), gebruikt u de volgende opdracht: -ext:.cpp.CPP.h.H Als u de TMH-bestanden voor de C++ en headerbestanden verschillende namen wilt geven, gebruikt u de optie -preserveext .
Bestandsextensies behouden	-preserveext:.ext1[.ext2]	Behoudt de opgegeven bestandsnaamextensies bij het maken van TMH-bestanden. TMH-bestanden voor alle bestandstypen hebben standaard de naam bestandsnaam.tmh. Dit heeft conflicten met de bestandsnaam veroorzaakt wanneer u meer dan één bronbestand met dezelfde naam hebt. TMH-bestanden voor C-bestanden (.c) en headerbestanden (.h) hebben bijvoorbeeld de naam <bestandsnaam.tmh>. Door -preserveext:.c .h te gebruiken, hebben de TMH-bestanden de naam <bestandsnaam.c.tmh> en <bestandsnaam.h.tmh>.
Uitvoermap	-odir:path	Hiermee geeft u de map voor de uitvoerbestanden die WPP maakt. Pad is het volledig gespecificeerde pad naar de map. De standaardwaarde is de lokale map.
Sjabloonbestand opgeven	-gen{ File.tpl }. ext	Voor elk bronbestand dat WPP verwerkt met de naam die tussen accolades {}is opgegeven, maakt u een ander bestand met de opgegeven bestandsnaamextensie. File.tpl vertegenwoordigt het bronbestand. *.ext vertegenwoordigt het type bestand dat is gemaakt en de bestandsnaamextensie. U kunt meerdere opties voor -gen opgeven. -gen{um-default.tpl}.tmh betekent bijvoorbeeld dat voor elk bestand um-default.tpl dat door WPP wordt verwerkt, een um-default.tmh-bestand wordt geproduceerd.
Configuratiegegevens scannen	-scan:Bestand	Zoekt naar configuratiegegevens, zoals aangepaste gegevenstypen, in een bestand dat geen configuratiebestand is, evenals in defaultwpp.ini. Plaats begin_wpp configuratie en end_wpp tekenreeksen rond de configuratiegegevens om deze te identificeren. Gebruik dezelfde indeling voor de configuratiegegevens als wordt gebruikt in defaultwpp.ini. Als u de configuratiegegevens hebt toegevoegd aan een aangepast configuratiebestand, gebruikt u de parameter -ini .
Alternatief configuratiebestand	-defwpp:path	Specificeert een alternatief configuratiebestand. Wpp gebruikt dit bestand in plaats van het defaultwpp.ini-bestand.
Extra configuratiebestand	-ini:Pad	Hiermee geeft u een extra configuratiebestand. WPP maakt gebruik van het opgegeven bestand naast het standaardbestand, defaultwpp.ini. Gebruik deze parameter wanneer u een nieuw configuratiebestand hebt gemaakt om configuratiegegevens op te slaan voor tracering. Als u de configuratiegegevens hebt toegevoegd aan een ander type bestand, zoals een bron- of headerbestand, gebruikt u de parameter -scan .

WPP-buildproces

Als WPP is ingeschakeld voor een stuurprogramma- of gebruikersmodustoepassing, roept het bouwen van het stuurprogramma of de toepassing de WPP-preprocessor aan voordat het stuurprogramma of de toepassingsbestanden worden gecompileerd.

Het WPP-buildproces voltooit de volgende stappen:

1. De WPP-preprocessor verwerkt WPP-macro's in elk bronbestand en maakt een headerbestand voor traceringsberichten voor elk bronbestand. De broncode wordt niet rechtstreeks gewijzigd.

2. Nadat de preprocessor van WPP de headerbestanden voor traceringsberichten heeft gemaakt, verwerkt de C-preprocessor de ingebouwde WPP-macro's in de headerbestanden van het traceringsbericht op een normale manier.