Dela via

Lägga till spårning av WPP-programvara i en Windows-drivrutin

Om du vill använda WPP-spårning i en spårningsprovider, till exempel en drivrutin i kernelläge eller ett program i användarläge, måste du lägga till kod (eller instrument) drivrutinskällans filer och ändra drivrutinsprojektet. I det här avsnittet beskrivs dessa steg.

Tips Det enklaste sättet att lägga till WPP-spårning i drivrutinen är att använda en av KMDF- eller UMDF-drivrutinsmallarna i Visual Studio. Om du använder mallarna är mycket av den kod som du behöver lägga till redan klar åt dig. I Visual Studio väljer du File > New > Projectoch väljer sedan WDF-projektet Windows Driver (användarläge eller kernelläge). WPP-makrona definieras i huvudfilen Trace.h som ingår som en del av projektet. Om du använder någon av mallarna kan du gå vidare till steg 5.

Steg 1: Definiera kontroll-GUID och spårningsflaggor

Varje spårningsprovider (till exempel en drivrutin eller app i användarläge) måste definieras unikt. Det gör du genom att lägga till det WPP_CONTROL_GUIDS makro som definierar ett kontroll-GUID, en identifierare och spårningsflaggor. Detta görs så att du kan identifiera och kontrollera när och vad du vill spåra. Varje drivrutin har vanligtvis ett separat kontroll-GUID, men en drivrutin kan ha flera guid för kontroll, eller så kan flera drivrutiner dela en kontroll-GUID.

För enkelhetens skull definieras det WPP_CONTROL_GUIDS makrot vanligtvis i en gemensam rubrikfil. Huvudfilen måste inkluderas (#include) i alla källfiler som du tänker instrumentera för spårning.

Så här lägger du till WPP_CONTROL_GUIDS makro i drivrutinen:

  1. Lägg till en ny C++-huvudfil i ditt Visual Studio-projekt som du kan använda för att definiera WPP-spårningsmakronen. Välj till exempel och håll (eller högerklicka) drivrutinen i Solution Explorer och välj Lägg till > Nytt objekt. Spara filen (till exempel Trace.h).

  2. Lägg till ett WPP_CONTROL_GUIDS makro för att ange ett eget namn för spårningsprovidern, definiera ett kontroll-GUID och definiera de spårningsflaggor som du kan använda för att kvalificera specifika spårningsmeddelanden.

    Makrot WPP_CONTROL_GUIDS har följande syntax:

    Syntax för WPP_CONTROL_GUIDS

    #define WPP_CONTROL_GUIDS \
    WPP_DEFINE_CONTROL_GUID(GUIDFriendlyName, (ControlGUID),  \
        WPP_DEFINE_BIT(NameOfTraceFlag1)  \
        WPP_DEFINE_BIT(NameOfTraceFlag2)  \
        .............................   \
        .............................   \
        WPP_DEFINE_BIT(NameOfTraceFlag31) \
        )

    Följande kod använder till exempel myDriverTraceGuid som GUIDFriendlyName. Observera att ControlGUID- har ett något annorlunda format än standardformen för ett 32-siffrigt hexadecimalt GUID. ControlGUID- har de fem fälten, men de avgränsas med kommatecken och hakparenteser, i stället för vanliga bindestreck och klammerparenteser. Du kan till exempel ange ((84bdb2e9,829e,41b3,b891,02f454bc2bd7) i stället för {84bdb2e9-829e-41b3-b891-02f454bc2bd7}.

    Exempel på en WPP_CONTROL_GUIDS-instruktion

    #define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(                                           \
        myDriverTraceGuid, (84bdb2e9,829e,41b3,b891,02f454bc2bd7), \
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        )

    Tips Du kan kopiera kodfragmentet till en rubrikfil. Se till att ändra kontrollens GUID och det vänliga namnet. Du kan använda GUIDgen.exe för att generera kontrollens GUID. Guidgen.exe ingår i Visual Studio (Tools > Create GUID). Du kan också använda verktyget Uuidgen.exe, som är tillgängligt från kommandotolken i Visual Studio (skriv uuidgen.exe /? för mer information).

  3. Definiera spårningsflaggor för din spårningsleverantör.

    De WPP_DEFINE_BIT elementen i WPP_CONTROL_GUIDS makrot definierar spårningsflaggor för spårningsprovidern. Flaggorna representerar vanligtvis allt mer detaljerade rapporteringsnivåer, men du kan använda flaggor som du vill som villkor för att generera spårningsmeddelanden. I det WPP_CONTROL_GUIDS exemplet definierar WPP_DEFINE_BIT fyra spårningsflaggor (MYDRIVER_ALL_INFO, TRACE_DRIVER, TRACE_DEVICE och TRACE_QUEUE).

    Du kan definiera upp till 31 spårningsflaggor. WPP tilldelar bitvärden till elementen i den ordning de visas, till exempel bit 0 (0x1), bit 1 (0x2), bit 2 (0x4), bit 3 (0x8) och så vidare. Du använder spårningsflaggor när du lägger till spårningsmeddelandefunktioner i källkoden (beskrivs i steg 5: Instrumentera drivrutinskoden för att generera spårningsmeddelanden vid lämpliga platser).

    Obs Med hjälp av spårningsflaggor kan du styra när specifika komponenter ska spåras (till exempel specifika I/O-begäranden eller aktiviteter för enhets- eller drivrutinsobjekt). Du lägger till spårningsflaggan i spårningsmeddelandet (till exempel DoTraceMessage (TRACE_DRIVER, "Hello World!\n"). När du skapar en spårningssession med en spårningskontrollant, till exempel Tracelog, anger du alternativet -flag att använda för spårningsprovidern i den sessionen, i det här fallet är flaggan bit 1 (0x1), vilket motsvarar flaggan TRACE_DRIVER. När du startar spårningssessionen skrivs alla spårningsmeddelanden som anger spårningsflaggan till loggen.

Steg 2: Välj vilka spårningsmeddelandefunktioner du tänker använda och definiera WPP-makron för dessa funktioner

Precis som en funktion för felsökningsutskrift är en spårningsmeddelandefunktion en funktion (eller ett makro) som du lägger till i koden för att skriva spårningsmeddelanden.

Välja en spårningsmeddelandefunktion

  1. Standardfunktionen för spårningsmeddelanden är DoTraceMessage makro. Om du använder standardfunktionen kan du styra när meddelanden ska genereras med hjälp av Spårningsflaggans värden och för din provider. Värdena för Spårningsflaggor är de flaggor som du definierade när du skapade kontroll-GUID:et i steg 1. Om du använder DoTraceMessageär standard-WPP-makron redan definierade för dig (WPP_LEVEL_ENABLED och WPP_LEVEL_LOGGER), så du kan hoppa över resten av det här steget och gå till steg 5.

  2. Om du använder någon av KMDF- eller UMDF-mallarna har funktionen TraceEvents och de nödvändiga WPP-makrona redan definierats för att aktivera funktionen, så du kan gå vidare till steg 5.

  3. Om du skapar en egen spårningsmeddelandefunktion eller konverterar den befintliga funktionen för felsökningsutskrift fortsätter du med resten av det här steget.

Skapa eller anpassa en spårningsmeddelandefunktion

  1. Om du använder anpassade spårningsmeddelandefunktioner eller vill konvertera felsökningsfunktioner (till exempel KdPrint) för att generera spårningsmeddelanden måste du definiera WPP-makron som identifierar och aktiverar funktionerna för spårningsmeddelanden i spårningsprovidern. Placera dessa makron i den Trace.h-huvudfil som du har lagt till i projektet.

  2. Definiera WPP-makron för att aktivera spårningsfunktionen.

    Varje spårningsmeddelandefunktion som du använder måste ha ett motsvarande par makron. Dessa makron identifierar spårningsprovidern och anger de villkor som genererar meddelandena. Du definierar vanligtvis ett par makron, WPP_<villkor>_LOGGER och WPP_<villkor>_ENABLED när det gäller standard-WPP_LEVEL_ENABLED och WPP_LEVEL_LOGGER makron.

Varje spårningsmeddelandefunktion som du använder måste ha ett motsvarande par makron. Dessa makron identifierar spårningsprovidern och anger de villkor som genererar meddelandena. Du definierar vanligtvis ett par makron, WPP_<villkor>_LOGGER och WPP_<villkor>_ENABLED när det gäller standard-WPP_LEVEL_ENABLED och WPP_LEVEL_LOGGER makron.

Begrepp Beskrivning

WPP_VILLKOR_LOGGER

Används för att hitta spårningssessionen som är associerad med providern och returnerar ett handtag till sessionen.

WPP_VILLKOR_AKTIVERAD

Används för att avgöra om loggning är aktiverat med det angivna villkoret.

För de WPP-makron som du definierar representerar VILLKOR de villkor som funktionen för spårningsmeddelanden stöder, i den ordning de visas i funktionens parameterlista, avgränsade med understreck. Standardfunktionen för spårningsmeddelanden, DoTraceMessage, stöder till exempel bara spårningsflagga som villkor, så det finns bara en parameter i makronamnen (WPP_LEVEL_ENABLED).

Obs Tyvärr verkar namnen på standardmakronen (WPP_LEVEL_ENABLED och WPP_LEVEL_LOGGER) indikera parametern spårningsnivå, men de refererar faktiskt till spårningsflaggan.

Om du använder en anpassad spårningsmeddelandefunktion kan du ange ytterligare kvalificerare, till exempel spårningsnivå. Spårningsnivån definieras i evntrace.h-filen, och spårningsnivåerna är ett praktiskt sätt att klassificera spårningsmeddelandena som felmeddelanden, varningar och informationsmeddelanden.

Du kan till exempel lägga till följande kodfragment i huvudfilen som du har lagt till i projektet. Följande kod definierar anpassade WPP-makron för en spårningsmeddelandefunktion som stöder både spårningsnivå och parametrar för spårningsflagga som villkor för att generera spårningsmeddelanden. Makrot WPP_LEVEL_FLAGS_ENABLED returnerar TRUE om loggning är aktiverat för det angivna FLAGS-värdet och det aktiverade LEVEL-värdet är större än eller lika med det nivåargument som används i funktionsanropet för spårningsmeddelandet.

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
           WPP_LEVEL_LOGGER(flags)

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
           (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)

Därefter måste du ange anpassade spårningsfunktioner i WPP-konfigurationsblocket (begin_wpp konfiguration och end_wpp) Om du till exempel använder mallen för UMDF- eller KMDF-drivrutinsprojekt i Visual Studio definierar mallen WPP-makron för en anpassad spårningsmeddelandefunktion som heter TraceEvents. Makrofunktionen TraceEvents använder spårningsnivå och spårningsflagga som villkor för att generera meddelanden. Om du har definierat WPP_LEVEL_FLAGS_ENABLED makrot i rubrikfilen Trace.h kan du lägga till följande makrodefinition.

//
// This comment block is scanned by the trace preprocessor to define the 
// TraceEvents function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//

Du kan också konvertera befintliga felsökningsutskrifter till spårningsmeddelanden genom att lägga till en liknande FUNC--deklaration i WPP-konfigurationsblocket. I följande exempel läggs till exempel koden för att konvertera befintliga KdPrint--instruktioner. Deklarationen FUNC definierar också globalt KdPrint- för att använda den angivna spårningsnivån och flaggan {LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}. I stället för att skicka utdata till felsökningsprogrammet skickas felsökningsuttrycken till spårningsloggen.

//
// This comment block is scanned by the trace preprocessor to define the
// TraceEvents function and conversion for KdPrint. Note the double parentheses for the KdPrint message, for compatibility with the KdPrint function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// FUNC KdPrint{LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}((MSG, ...));
// end_wpp
//

Obs Om du vill konvertera KdPrintEx till en spårningsmeddelandefunktion måste du utföra några extra steg. Jämfört med KdPrinttar funktionen KdPrintEx två ytterligare argument. Om du vill konvertera funktionen KdPrintEx måste du definiera en WPP_DEFINE_BIT för ComponentIDoch definiera anpassade WPP_<villkor>_LOGGER och WPP_<villkor>_ENABLED makron. Den andra parametern för KdPrintEx specificerar nivån och är liknande värdena för Trace Level, så du behöver inte nödvändigtvis omdefiniera dem.


#define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(\
    myDriverTraceGuid, (11C3AAE4, 0D88, 41b3, 43BD, AC38BF747E19), \    /* change GUID for your provider */
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        WPP_DEFINE_BIT(DPFLTR_IHVDRIVER_ID)      /* bit  4 = 0x00000010 */\         /* Added for the ComponentID param of KdPrintEx */
    )

#define WPP_Flags_LEVEL_LOGGER(Flags, level)                                  \
    WPP_LEVEL_LOGGER(Flags)

#define WPP_Flags_LEVEL_ENABLED(Flags, level)                                 \
    (WPP_LEVEL_ENABLED(Flags) && \
    WPP_CONTROL(WPP_BIT_ ## Flags).Level >= level)



//
// This comment block is scanned by the trace preprocessor to convert the KdPrintEx function.
// Note the double parentheses for the KdPrint message, for compatiblility with the KdPrintEx function.
//
// begin_wpp config
// FUNC KdPrintEx((Flags, LEVEL, MSG, ...));   
// end_wpp
//

Steg 3: Inkludera de associerade spårningshuvudfilerna (.h och .tmh) i C- eller C++-källfilerna

Om du har definierat kontrollens GUID och spårningsflaggor för drivrutinen i en huvudfil (till exempel trace.h), måste du inkludera huvudfilen i källfilerna där du initierar och avlastar WPP (steg 4) eller anropar spårningsmeddelandefunktioner.

Dessutom måste du lägga till en #include-instruktion för Trace Message Header File (.tmh). När du skapar drivrutinen eller programmet genererar WPP-förprocessorn huvudfilerna för spårningsmeddelanden (.tmh) för varje källfil som innehåller funktioner för spårningsmeddelanden.

/* -- driver.c  - include the *.tmh file that is generated by WPP --*/

#include "trace.h"     /* file that defines WPP_CONFIG_GUIDS and trace flags */
#include "driver.tmh"  /* this file is auto-generated */

Steg 4: Lägg till makron i lämpliga återanropsfunktioner för att initiera och rensa WPP

Initialisera WPP vid drivrutinsstarten

  • Lägg till WPP_INIT_TRACING makrot i DriverEntry rutin för en drivrutin i kernelläge eller UMDF 2.0-drivrutinen, eller till DLLMain rutin för en drivrutin i användarläge (UMDF 1.x) eller ett program.

Rensa WPP-resurser vid föraravslutning

  • Lägg till WPP_CLEANUP makrot i drivrutinens avlastningsrutin (till exempel DriverContextCleanup eller DriverUnload) för en drivrutin i kernelläge eller EN UMDF 2.0-drivrutin.

    För en drivrutin i användarläge (UMDF 1.x) eller ett program lägger du till WPP_CLEANUP makrot i DLLMain- rutin.

    Du bör också lägga till makrot WPP_CLEANUP i rutinen DriverEntry om DriverEntry misslyckas. Om till exempel DriverEntry- misslyckas anropas inte drivrutinens avlastningsrutin. Se anropet till WdfDriverCreate i följande exempel.

Exempel på en drivrutin i kernelläge som använder WPP_INIT_TRACING och WPP_CLEANUP i DriverEntry


NTSTATUS
DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    )
{  

          //  ... 

                //
    // Initialize WPP Tracing in DriverEntry
    //
    WPP_INIT_TRACING( DriverObject, RegistryPath );

                //  ...


 //
    // Create a framework driver object to represent our driver.
    //
    status = WdfDriverCreate(
        DriverObject,
        RegistryPath,
        &attributes, // Driver Object Attributes
        &config,          // Driver Config Info
        WDF_NO_HANDLE // hDriver
        );

    if (!NT_SUCCESS(status)) {

        TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT,
                "WdfDriverCreate failed with status 0x%x\n", status);
        //
        // Cleanup tracing here because DriverContextCleanup will not be called
        // as we have failed to create WDFDRIVER object itself.
        // Please note that if you return failure from DriverEntry after the
        // WDFDRIVER object is created successfully, you don't have to
        // call WPP cleanup because in those cases DriverContextCleanup
        // will be executed when the framework deletes the DriverObject.
        //
        WPP_CLEANUP(DriverObject);

    }

                return status;

}

Exempel på en drivrutin i kernelläge med WPP_CLEANUP i DriverContextCleanup



VOID
DriverContextCleanup(
       PDRIVER_OBJECT DriverObject
       )
{
    // ...

    // Clean up WPP resources on unload
    //
    WPP_CLEANUP(DriverObject);

   // ...

}

Exempel för UMDF 2.0-drivrutin med WPP_INIT_TRACING i DriverEntry


/
// Driver specific #defines in trace header file (trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF2.0\\UMDF2_0Driver1 V1.0"


 // Initialize WPP Tracing in the DriverEntry routine
 //
    WPP_INIT_TRACING( MYDRIVER_TRACING_ID );

Exempel för UMDF 1.0-drivrutinsanvändning av WPP_INIT_TRACING- och WPP_CLEANUP makron i DLLMain

/
// Driver specific #defines in trace header file (for example, trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF1.X\\UMDF1_XDriver1"


//
// DLL Entry Point - UMDF 1.0 example in the source file where you implement the DLL exports.
// 

extern "C"
BOOL
WINAPI
DllMain(
    HINSTANCE hInstance,
    DWORD dwReason,
    LPVOID lpReserved
    )
{
    if (dwReason == DLL_PROCESS_ATTACH) {
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);              // Initialize WPP tracing

        g_hInstance = hInstance;
        DisableThreadLibraryCalls(hInstance);

    } else if (dwReason == DLL_PROCESS_DETACH) {
        WPP_CLEANUP();                                                                                                              // Deactivate and cleanup WPP tracing
    }

    return _AtlModule.DllMain(dwReason, lpReserved);
}

Steg 5: Instrumentera drivrutinskoden för att generera spårningsmeddelanden vid lämpliga platser

Du kan använda valfri spårningsmeddelandefunktion som du väljer, förutsatt att funktionen för spårningsmeddelanden, spårningsflaggor och nivåer definieras på rätt sätt. Standardfunktionen för spårningsmeddelanden är DoTraceMessage makro. Du kan lägga till det här makrot i koden för att skriva meddelanden till loggfilen. I följande tabell visas några av de fördefinierade funktionerna för spårningsmeddelanden och de felsökningsutskriftsfunktioner som du kan använda för att skapa spårningsmeddelanden.

Exempel på spårningsmeddelandefunktioner När du ska använda
DoTraceMessage

Det här är standardfunktionen för spårningsmeddelanden. Fördelen med att använda DoTraceMessage är att funktionen redan har definierats åt dig. Du kan använda spårningsflaggor som du anger i makrot WPP_CONFIG_GUIDS. Nackdelen med att använda DoTraceMessageär att funktionen bara tar en villkorsparameter, det vill ex. spårningsflaggor. Om du vill använda spårningsnivåer kan du använda DoDebugTrace makro eller använda TraceEvents, som använder både spårningsflaggor och spårningsnivåer för att logga endast fel- eller varningsmeddelanden.
TraceEvents

Om du skapar en drivrutin med hjälp av WDF-mallar i Visual Studio är detta standardfunktionen för spårningsmeddelanden. Fördelen med att använda TraceEvents är att funktionen för spårningsmeddelanden, spårningsflaggor och spårningsnivå redan har definierats åt dig. Dessutom innehåller mallarna även instrumentation som skriver meddelanden till loggfilen vid funktionsinmatning och utgång.
KdPrint, KdPrintEx, DbgPrint, DbgPrintEx

Fördelen med att använda funktionerna för felsökningsutskrift är att du inte behöver ändra dina befintliga felsökningsuttryck. Du kan enkelt växla från att visa meddelanden i felsökningsprogrammet till att registrera spårningsmeddelanden i en fil. Om du har anpassat spårningsmeddelandefunktionen så att den innehåller någon av felsökningsutskriftsfunktionerna behöver du inte utföra mer arbete. När du skapar en spårningssession med Logman eller Tracelog, eller en annan spårningskontrollant, anger du bara flaggor och nivåer för providern. Alla felsökningsuttryck som uppfyller de villkor som du anger skrivs ut i loggen.

Använda DoTraceMessage-instruktioner

  1. Lägg till DoTraceMessage- makro i koden som du skulle göra med en felsökningsrutin. Makrot DoTraceMessage tar tre parametrar: flaggnivån (TraceFlagName), som definierar villkoret när spårningsmeddelandet skrivs, Meddelande sträng och den valfria variabellistan.

    DoTraceMessage(TraceFlagName, Message, [VariableList... ]

    Följande DoTraceMessage--instruktion skriver till exempel namnet på funktionen som innehåller instruktionen DoTraceMessage när flaggan TRACE_DRIVER, enligt definitionen i WPP_CONTROL_GUIDS, aktiveras för spårningssessionen.

         DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

    I exemplet används en fördefinierad sträng för funktionen som körs för närvarande (%FUNC!). Mer information om specifikationssträngar för WPP-definierade format finns i Vad är specifikationssträngarna för utökat WPP-format?

  2. Skapa spårningsmeddelandet genom att skapa en spårningssession för din spårningsprovider med hjälp av Logman eller Tracelogoch ange en flagga som ställer in TRACE_DRIVER-flaggan (bit 1, 0x2).

//
//  DoTraceMessage examples
// 

     ...

// writes the name of the function that contains the trace statement when the flag, TRACE_DRIVER (bit 1, 0x2), 
// as defined in WPP_CONTROL_GUIDS, is enabled for the trace session.

     DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

     ...

// writes the name of the function, the line number, and the error code 

      DoTraceMessage(
            TRACE_DRIVER,
            "[%s] Failed at %d (error code= %d)\n",
            __FUNCTION__,
            __LINE__,
            dwLastError);

Om du använder Windows-drivrutinsmallarna i Visual Studio definieras makrot TraceEvents åt dig i trace.h-huvudfilen.

Använda TraceEvents-instruktioner

  1. Lägg till TraceEvents makro i koden på samma sätt som du skulle göra med en debugutskrift. Makrot TraceEvents tar följande parametrar: spårningsnivån (Nivå) och spårningsflaggan (Flaggor), som definierar villkoret när spårningsmeddelandet skrivs, Meddelande sträng och den valfria variabellistan.

    TraceEvents(Level, Flags, Message, [VariableList... ]

    Följande TraceEvents--instruktion skriver till exempel namnet på funktionen som innehåller instruktionen TraceEvents när villkoren som anges i parametrarna Spårningsnivå och Spårningsflagga uppfylls. Spårningsnivån är ett heltalsvärde. allt på eller under den spårningsnivå som anges för den spårningssessionen kommer att spåras. TRACE_LEVEL_INFORMATION definieras i Evntrace.h och har värdet 4. Flaggan TRACE_DRIVER (bit 1, 0x2) definieras i WPP_CONTROL_GUIDS. Om den här TRACE_DRIVER biten har angetts för spårningssessionen och spårningsnivån är 4 eller högre skriver TraceEvents spårningsmeddelandet.

            TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

    I exemplet används en fördefinierad sträng för funktionen som körs för närvarande (%FUNC!). Mer information om specifikationssträngar för WPP-definierade format finns i Vad är specifikationssträngarna för utökat WPP-format?

  2. Skapa en spårningssession för spårningsprovidern genom att använda Logman eller Tracelogför att generera spårningsmeddelandet. Ange en spårningsnivå till TRACE_LEVEL_INFORMATION (4) eller högre och ange en spårningsnivå som sätter TRACE_DRIVER-biten (bit 1, 0x2).

//
//  TraceEvents examples
// 


    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

//


    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                       "OSRUSBFX2 Driver Sample - Driver Framework Edition.\n");

    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                "Built %s %s\n", __DATE__, __TIME__);

Steg 6: Ändra Visual Studio-projektet för att köra WPP-förprocessorn och skapa lösningen

WDK:n har stöd för WPP Preprocessor, så att du kan köra förprocessorn med hjälp av Visual Studio och MSBuild-miljön.

Så här kör du WPP-förprocessorn

  1. Välj och håll (eller högerklicka) drivrutinsprojektet i Solutions Explorer och välj Egenskaper.
  2. På projektegenskapssidan väljer du Konfigurationsegenskaper och väljer WPP-spårning.
  3. Under Allmäntställer du in alternativet Kör WPP till Ja.
  4. Under kommandoradlägger du till ytterligare alternativ för att anpassa spårningsbeteendet. Information om vad du kan lägga till finns i WPP Preprocessor.
  5. Skapa projektet eller lösningen för målkonfigurationen och plattformen. Se Skapa en drivrutin med WDK-.

Information om byggprocessen finns i TraceWPP-uppgift och WDK- och Visual Studio-byggmiljö.

Du kan också köra förprocessorn separat från byggmiljön med hjälp av Verktyget TraceWPP (TraceWPP.exe). Det här verktyget finns i underkatalogen bin/x86 och bin/x64 för WDK.

Steg 7: Starta en spårningssession för att samla in och verifiera dina spårningsmeddelanden

För att kontrollera att du har konfigurerat WPP-spårning korrekt bör du installera drivrutinen eller programmet på en testdator och sedan skapa en spårningssession för att samla in spårningsmeddelandena. Du kan skapa en spårningssession för spårningsprovidern med hjälp av valfri spårningskontrollant, till exempel Logman, Tracelogeller TraceView. Du kan få meddelandena skrivna till en loggfil eller skickas till ett kernelfelsökare. Beroende på de spårningsmeddelandefunktioner du använder måste du ange de spårningsflaggor och spårningsnivåer som ska generera meddelandena.

Om du till exempel använder de spårningsnivåer som definierats i Evntrace.h och vill samla in TRACE_LEVEL_INFORMATION (4) eller senare måste du ange nivån till 4. När du anger nivån till 4 för spårningssessionen samlas även alla informationsmeddelanden (4), varningsmeddelanden (3), fel (2) och kritiska (1) in, förutsatt att alla andra villkor, till exempel spårningsflaggor, också uppfylls.

För att verifiera att alla dina meddelanden genereras kan du ställa in spårningsnivån och spårningsflaggor på högsta värden så att alla meddelanden genereras. Spårningsflaggor använder en bitmask (ULONG), så att du kan ange alla bitar (till exempel 0xFFFFFFFF). Spårningsnivåer representeras av ett bytevärde. Om du till exempel använder Logman kan du ange 0xFF för att täcka alla nivåer.

(Exempel) Starta en spårningssession med Logman

logman create trace "myWPP_session" -p {11C3AAE4-0D88-41b3-43BD-AC38BF747E19} 0xffffffff 0xff -o c:\DriverTest\TraceFile.etl 

logman start "myWPP_session"

logman stop "myWPP_session"

(Exempel) Starta en spårningssession med Hjälp av TraceLog

tracelog -start MyTrace -guid  MyProvider.guid -f d:\traces\testtrace.etl -flag 2 -level 0xFFFF

Kommandot Tracelog innehåller parametern -f för att ange namn och plats för händelsespårningsloggfilen. Den innehåller parametern -flag för att ange flagguppsättningen och parametern -level för att ange nivåinställningen. Du kan utelämna dessa parametrar, men vissa spårningsprovidrar genererar inga spårningsmeddelanden om du inte anger flaggan eller nivån. trace level definieras i Evntrace.h-filen, och spårningsnivåerna ger ett bekvämt sätt att klassificera spårningsmeddelandena som kritiska, fel,varnings- och informationsmeddelanden.