Freigeben über

TraceLogging Wrapper-Makros

  • Artikel

Die TraceLoggingWrite und TraceLoggingWriteActivity Makros emittieren TraceLogging-Ereignisse, die gemäß den Makroparametern konfiguriert sind. Jedes dieser Makros akzeptiert eine Reihe erforderlicher Parameter, gefolgt von bis zu 99 optionalen Parametern. Jeder optionale Parameter konfiguriert entweder das Ereignis oder fügt dem Ereignis ein Feld hinzu. Jeder optionale Parameter muss eines der auf dieser Seite beschriebenen TraceLogging Wrapper-Makros sein.

Zum Beispiel:

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

In diesem Beispiel sind g_hProvider und "MyEvent1" die erforderlichen Parameter. Sie geben den Anbieter an, der für das Ereignis und den Namen des Ereignisses verwendet werden soll. Jeder der verbleibenden Parameter ist ein Wrappermakro. Die Parameter TraceLoggingLevel und TraceLoggingKeyword konfigurieren das Ereignis. Die Parameter TraceLoggingString und TraceLoggingHResult fügen dem Ereignis Felder hinzu.

Ereigniskonfigurationsmakros

Die folgenden Makros konfigurieren das Ereignis.

Wenn im TraceLoggingWrite-kein bestimmtes Konfigurationsmakro bereitgestellt wird, wird für dieses Ereignis ein Standardwert verwendet. Wenn z. B. kein TraceLoggingLevel Parameter für ein Ereignis verwendet wird, verwendet das Ereignis die Standardebene 5 (VERBOSE).

  • TraceLoggingLevel legt die Ebene des Ereignissesfest. Die Ebene ist ein 8-Bit-Wert, der den Schweregrad des Ereignisses angibt. Ebenen von 1 (WINEVENT_LEVEL_CRITICAL) bis 5 (WINEVENT_LEVEL_VERBOSE) werden in <winmeta.h>definiert. Wenn nicht angegeben, wird das Ereignis standardmäßig auf Ebene 5 (VERBOSE) festgelegt. Level ist ein wichtiger Bestandteil des ETW-Ereignisroutings und der Filterung, sodass alle Ereignisse eine sinnvolle Nicht-Null-Ebene aufweisen sollten.
  • TraceLoggingKeyword legt das Schlüsselwort des Ereignissesfest. Ein Schlüsselwort ist ein 64-Bit-Wert mit jedem Bit, der eine Kategorie angibt, zu der das Ereignis gehört. Die niedrigen 48 Bits des Schlüsselworts werden vom Besitzer des Anbieters definiert, während die hohen 16 Bits des Schlüsselworts von Microsoft definiert werden. Sie können beispielsweise festlegen, dass alle Anbieter mit dem Namen "MyCompany.MyComponent" das Schlüsselwort 0x1 verwenden, um "Networking" zu bedeuten. Wenn nicht angegeben, wird das Ereignis standardmäßig als Schlüsselwort 0x0 (None) festgelegt. Das Schlüsselwort ist ein wichtiger Bestandteil des ETW-Ereignisroutings und der Filterung, sodass alle Ereignisse ein aussagekräftiges Schlüsselwort ungleich Null aufweisen sollten.
  • TraceLoggingOpcode legt die opcode-des Ereignisses fest. Der Opcode ist ein 8-Bit-Wert, der spezielle Semantik für das Ereignis angibt, z. B. dass das Ereignis den Anfang (WINEVENT_OPCODE_START) oder das Ende (WINEVENT_OPCODE_STOP) einer ETW-Aktivität (eine Gruppe verwandter Ereignisse) erfasst. Wenn nicht angegeben, wird standardmäßig opcode 0 (WINEVENT_OPCODE_INFO) verwendet, der angibt, dass keine spezielle Semantik erforderlich ist.
  • TraceLoggingChannel legt den Kanal des Ereignissesfest. Der Kanal ist ein 8-Bit-Wert, der für verschiedene Zwecke verwendet wird. Wenn nicht angegeben, wird das Ereignis standardmäßig auf Kanal 11 (WINEVENT_CHANNEL_TRACELOGGING) festgelegt. Die meisten Ereignisse müssen den Kanal des Ereignisses nicht ändern und sollten nicht TraceLoggingChannel-verwenden.
  • TraceLoggingEventTag legt das Tag des Ereignisses fest. Das Tag ist ein 28-Bit-Wert mit vom Anbieter definierter Semantik. Beispielsweise kann ein Anbieter Tag-Bit-0x1000000 definieren, um anzugeben, dass das Ereignis potenziell persönlich identifizierbare Informationen enthält und eine spezielle Behandlung von anbieterspezifischen Ereignisverarbeitungstools erhalten soll. Wenn nicht angegeben, wird das Tag standardmäßig auf 0 festgelegt.
  • TraceLoggingDescription legt die Beschreibung des Ereignisses fest. Die Beschreibung ist ein Zeichenfolgenliteral mit einer lesbaren Beschreibung des Ereignisses. Dies dient als Kommentar zum Ereigniszweck, und die Beschreibung wird auch als Anmerkung in den Debugsymbolen Ihrer Komponente (PDB) aufgezeichnet. Wenn nicht angegeben, wird die Beschreibung standardmäßig auf ""festgelegt.
  • TraceLoggingCustomAttribute fügt den Debugsymbolen der Komponente (PDB) eine Schlüsselwertanmerkung hinzu.

Feldmakros

TraceLogging unterstützt viele Wrappermakros zum Hinzufügen von Feldern zu einem Ereignis. Jedes Feld ist ein Name-Wert-Paar. Beispielsweise würde TraceLoggingInt32(argc, "ArgCount") ein INT32-Feld mit dem Namen "ArgCount" mit dem Wert argchinzufügen.

Die meisten Feldwrappermakros akzeptieren ähnliche Parameter:

  • Wert: Ein Ausdruck, der zur Laufzeit ausgewertet wird, um die daten zu bestimmen, die in das Feld eingeschlossen werden sollen. Die meisten Feldwrappermakros verwenden einen einzelnen Parameter, um den Wert anzugeben. Einige Makros erfordern jedoch mehrere Parameter für den Feldwert, z. B. einen Zeiger und eine Länge. Die Wertparameter sind immer erforderlich.
    • In einigen Fällen wird der Feldwert als pszValueangegeben. In diesem Fall handelt es sich um einen Zeiger auf eine 0-beendete Zeichenfolge von Zeichen, die in das Feld eingeschlossen werden sollen. pszValue kann NULL sein, in diesem Fall ist der Feldwert eine leere Zeichenfolge "".
    • In einigen Fällen wird der Feldwert als pchValue-angegeben. In diesem Fall handelt es sich um einen Zeiger auf eine Zeichenfolge mit cchValue Zeichen, die in das Feld eingeschlossen werden sollen. pchValue- darf nur NULL sein, wenn cchValue- 0 ist.
    • In einigen Fällen wird der Feldwert als pValue- mit einer automatisch festgelegten Größe (kein cbValue Parameter) angegeben. In diesem Fall handelt es sich um einen Zeiger auf den Wert, der in das Feld eingeschlossen werden soll. pValue- darf nicht NULL sein.
    • In einigen Fällen wird der Feldwert als pValue- mit einem cbValue- Parameter angegeben, um die Größe (in Byte) der daten anzugeben, die in das Feld eingeschlossen werden sollen. pValue- darf nur NULL sein, wenn cbValue- 0 ist.
  • Name: Eine Zeichenfolgenliteral (Kompilierungszeitkonstante) mit dem Namen, der für das Feld verwendet werden soll. Für die meisten Feldwrappermakros ist kein Nameparameter erforderlich. Wenn Sie den Namensparameter weglassen, wird der Name des Felds basierend auf dem Präprozessortext des Werts des Makros, pszValue, pchValueoder pValue Parameter bestimmt. Beispielsweise entspricht TraceLoggingInt32(x[4] + y)TraceLoggingInt32(x[4] + y, "x[4] + y"). Beide würden dem Ereignis ein Feld namens "x[4] + y" mit einem Wert hinzufügen, der durch die Auswertung des Ausdrucks x[4] + ybestimmt wird.
  • Beschreibung: Eine Zeichenfolgenliteral (Kompilierungszeitkonstante) mit einer Beschreibung, die für das Feld verwendet werden soll. Dies wird hauptsächlich als praktischer Ort zum Platzieren eines Kommentars für das Feld verwendet, aber die Beschreibung wird auch als Anmerkung in den Debugsymbolen der Komponente (PDB) aufgezeichnet. Die Beschreibung ist optional. Wenn der Beschreibungsparameter nicht angegeben wird, wird die Beschreibung des Felds standardmäßig auf ""festgelegt.
  • Tag: Eine 28-Bit-Ganzzahl (Kompilierungszeitkonstante) mit vom Anbieter definierter Semantik. Beispielsweise kann ein Anbieter Tag-0x2 definieren, um anzugeben, dass das Feld eine Telefonnummer enthält und eine spezielle Behandlung von anbieterspezifischen Ereignisverarbeitungstools erhalten soll. Wenn der Tagparameter nicht angegeben wird, wird das Tag des Felds standardmäßig auf 0 festgelegt.

Beispielsweise haben die folgenden Wrappermakroaufrufe dieselbe Wirkung:

  • TraceLoggingInt32(argc)
  • TraceLoggingInt32(argc, "argc")
  • TraceLoggingInt32(argc, "argc", "")
  • TraceLoggingInt32(argc, "argc", "", 0)

Skalare

  • TraceLoggingValue(value, [name, ...]):

    Fügt ein Feld mit einem Typ hinzu, der automatisch vom Typ des Wertparameters abgeleitet wird. (nur C++)-

  • TraceLoggingInt8(value, [name, ...]):

    Fügt ein Feld mit einem INT8-Wert hinzu.

  • TraceLoggingUInt8(value, [name, ...]):

    Fügt ein Feld mit einem UINT8-Wert hinzu.

  • TraceLoggingInt16(value, [name, ...]):

    Fügt ein Feld mit einem INT16-Wert hinzu.

  • TraceLoggingUInt16(value, [name, ...]):

    Fügt ein Feld mit einem UINT16-Wert hinzu.

  • TraceLoggingInt32(value, [name, ...]):

    Fügt ein Feld mit einem INT32-Wert hinzu.

  • TraceLoggingUInt32(Wert, [Name, ...]):

    Fügt ein Feld mit einem UINT32-Wert hinzu.

  • TraceLoggingInt64(value, [name, ...]):

    Fügt ein Feld mit einem INT64-Wert hinzu.

  • TraceLoggingUInt64(value, [name, ...]):

    Fügt ein Feld mit einem UINT64-Wert hinzu.

  • TraceLoggingIntPtr(value, [name, ...]):

    Fügt ein Feld mit einem INT_PTR Wert hinzu (signierte ganze Zahl mit der gleichen Größe wie ein Zeiger).

  • TraceLoggingUIntPtr(value, [name, ...]):

    Fügt ein Feld mit einem UINT_PTR Wert hinzu (nicht signierte ganze Zahl mit der gleichen Größe wie ein Zeiger).

  • TraceLoggingLong(value, [name, ...]):

    Fügt ein Feld mit einem LONG-Wert (signiert long int, 32-Bits auf Windows-Plattformen) hinzu.

  • TraceLoggingULong(value, [name, ...]):

    Fügt ein Feld mit einem ULONG-Wert hinzu (unsigned long int, 32-Bits auf Windows-Plattformen).

  • TraceLoggingHexInt8(value, [name, ...]):

    Fügt ein Feld mit einem INT8-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexUInt8(Wert; [Name, ...]):

    Fügt ein Feld mit einem UINT8-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexInt16(value, [name, ...]):

    Fügt ein Feld mit einem INT16-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexUInt16(Wert, [Name, ...]):

    Fügt ein Feld mit einem UINT16-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexInt32(Wert; [Name; ...]):

    Fügt ein Feld mit einem INT32-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexUInt32(Wert, [Name, ...]):

    Fügt ein Feld mit einem UINT32-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexInt64(Wert, [Name, ...]):

    Fügt ein Feld mit einem INT64-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexUInt64(Wert; [Name; ...]):

    Fügt ein Feld mit einem UINT64-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexIntPtr(value, [name, ...]):

    Fügt ein Feld mit einem INT_PTR Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexUIntPtr(value, [name, ...]):

    Fügt ein Feld mit einem UINT_PTR Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexLong(wert; [Name, ...]):

    Fügt ein Feld mit einem LONG-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingHexULong(wert; [Name, ...]):

    Fügt ein Feld mit einem ULONG-Wert mit einem Hexadezimalformatierungshinweis hinzu.

  • TraceLoggingFloat32(value, [name, ...]):

    Fügt ein Feld mit einem FLOAT-Wert (32-Bit-Gleitkomma) hinzu.

  • TraceLoggingFloat64(value, [name, ...]):

    Fügt ein Feld mit einem DOUBLE-Wert (64-Bit-Gleitkomma) hinzu.

  • TraceLoggingBoolean(value, [name, ...]):

    Fügt ein Feld mit einem booleschen 8-Bit-Wert hinzu (Win32 BOOLEAN oder C++-bool).

  • TraceLoggingBool(value, [name, ...]):

    Fügt ein Feld mit einem booleschen 32-Bit-Wert (Win32 BOOL) hinzu.

  • TraceLoggingChar(value, [name, ...]):

    Fügt ein Feld mit einem char Wert hinzu (8-Bit-Ganzzahl mit Hinweis zur Zeichenfolgenformatierung, in der Regel als Codepage 1252 behandelt).

  • TraceLoggingChar16(value, [name, ...]):

    Fügt ein Feld mit einem char16_t Wert hinzu (16-Bit-Ganzzahl mit Hinweis zur Zeichenfolgenformatierung, in der Regel als UCS-2 behandelt).

  • TraceLoggingWChar(value, [name, ...]):

    Fügt ein Feld mit einem wchar_t Wert hinzu (identisch mit char16_t auf Windows-Plattformen).

  • TraceLoggingPointer(value, [name, ...]):

    Fügt ein Feld mit einem void* Wert (Zeigergröße mit einem Hexadezimalformathinweis) hinzu.

  • TraceLoggingCodePointer(value, [name, ...]):

    Fügt ein Feld mit einem void* Wert (Zeigergröße mit einem Codezeigerformathinweis) hinzu.

  • TraceLoggingPid(value, [name, ...]):

    Fügt ein Feld mit einem INT32-Wert mit einem Hinweis zur Prozess-ID-Formatierung hinzu.

  • TraceLoggingTid(value, [name, ...]):

    Fügt ein Feld mit einem INT32-Wert mit einem Hinweis zur Thread-ID-Formatierung hinzu.

  • TraceLoggingIPv4Address(value, [name, ...]):

    Fügt ein Feld mit einem UINT32-Wert mit einem IPv4-Formatierungshinweis (Netzwerkbytereihenfolge) hinzu.

  • TraceLoggingIPv6Address(pValue, [Name, ...]):

    Fügt ein Feld mit einem 16-Byte-Binärwert mit einem IPv6-Formatierungshinweis hinzu.

  • TraceLoggingPort(value, [name, ...]):

    Fügt ein Feld mit einem UINT16-Wert mit einem IP-Portformatierungshinweis (Netzwerkbytereihenfolge) hinzu.

  • TraceLoggingSocketAddress(pValue, cbValue, [Name, ...]):

    Fügt ein Feld mit einem SOCKADDR--Wert hinzu.

  • TraceLoggingWinError(value, [name, ...]):

    Fügt ein Feld mit einem UINT32-Wert mit einem Win32-Fehlercodeformatierungshinweis hinzu.

  • TraceLoggingNTStatus(value, [name, ...]):

    Fügt ein Feld mit einem NTSTATUS -Wert (LONG) mit einem WinNT-Fehlercodeformatierungshinweis hinzu.

  • TraceLoggingHResult(value, [name, ...]):

    Fügt ein Feld mit einem HRESULT -Wert (LONG) mit einem Windows HRESULT-Formatierungshinweis hinzu.

  • TraceLoggingFileTime(value, [name, ...]):

    Fügt ein Feld mit einem FILETIME--Wert hinzu. Bei Verwendung im C-Code muss der parameter value ein lvalue-Ausdruck sein.

  • TraceLoggingFileTimeUtc(value, [name, ...]):

    Fügt ein Feld mit einem FILETIME Wert mit einem UTC-Zeitzonenformatierungshinweis hinzu. Bei Verwendung im C-Code muss der parameter value ein lvalue-Ausdruck sein.

  • TraceLoggingSystemTime(value, [name, ...]):

    Fügt ein Feld mit einem SYSTEMTIME--Wert hinzu. Bei Verwendung im C-Code muss der parameter value ein lvalue-Ausdruck sein.

  • TraceLoggingSystemTimeUtc(value, [name, ...]):

    Fügt ein Feld mit einem SYSTEMTIME- Wert mit einem UTC-Zeitzonenformatierungshinweis hinzu. Bei Verwendung im C-Code muss der parameter value ein lvalue-Ausdruck sein.

  • TraceLoggingGuid(value, [name, ...]):

    Fügt ein Feld mit einem GUID- Wert hinzu. Bei Verwendung im C-Code muss der parameter value ein lvalue-Ausdruck sein.

  • TraceLoggingString(pszValue, [Name, ...]):

    Fügt ein Feld mit einer 0 beendeten char Zeichenfolge hinzu (in der Regel als Codepage 1252 behandelt). Wenn pszValue NULL ist, wird eine leere Zeichenfolge "" als Feldwert verwendet.

  • TraceLoggingUtf8String(pszValue, [Name, ...]):

    Fügt ein Feld mit einer 0 beendeten char Zeichenfolge mit einem UTF-8-Formatierungshinweis hinzu. Wenn pszValue NULL ist, wird eine leere Zeichenfolge "" als Feldwert verwendet.

  • TraceLoggingString16(pszValue, [Name, ...]):

    Fügt ein Feld mit einer 0 beendeten char16_t Zeichenfolge (UTF-16) hinzu. Wenn pszValue NULL ist, wird eine leere Zeichenfolge u"" als Feldwert verwendet.

  • TraceLoggingWideString(pszValue, [Name, ...]):

    Fügt ein Feld mit einer 0 beendeten wchar_t Zeichenfolge (UTF-16 unter Windows) hinzu. Wenn pszValue NULL ist, wird eine leere Zeichenfolge L"" als Feldwert verwendet.

  • TraceLoggingCountedString(pchValue, cchValue, [Name, ...]):

    Fügt ein Feld mit einer gezählten char Zeichenfolge hinzu (normalerweise als Codepage 1252 behandelt). pchValue kann nur NULL sein, wenn cchValue 0 ist.

  • TraceLoggingCountedUtf8String(pchValue, cchValue, [Name, Beschreibung, Tag]):

    Fügt ein Feld mit einer gezählten char Zeichenfolge mit einem UTF-8-Formatierungshinweis hinzu. pchValue kann nur NULL sein, wenn cchValue 0 ist.

  • TraceLoggingCountedString16(pchValue, cchValue, [Name, ...]):

    Fügt ein Feld mit einer gezählten char16_t Zeichenfolge (UTF-16) hinzu. pchValue kann nur NULL sein, wenn cchValue 0 ist.

  • TraceLoggingCountedWideString(pchValue, cchValue, [Name, Beschreibung, Tag]):

    Fügt ein Feld mit einer gezählten wchar_t Zeichenfolge (UTF-16 unter Windows) hinzu. pchValue kann nur NULL sein, wenn cchValue 0 ist.

  • TraceLoggingAnsiString(pValue, [Name, ...]):

    Fügt ein Feld mit einem ANSI_STRING Wert hinzu. Der pValue-Zeiger darf nicht NULL sein.

  • TraceLoggingUnicodeString(pValue, [Name, ...]):

    Fügt ein Feld mit einem UNICODE_STRING Wert hinzu. Der pValue-Zeiger darf nicht NULL sein.

  • TraceLoggingSid(pValue, [Name, ...]):

    Fügt ein Feld mit einem SID- Wert hinzu. Der pValue-Zeiger darf nicht NULL sein und muss auf eine ordnungsgemäß initialisierte SID zeigen (Revision und SubAuthorityCount muss gültig sein).

  • TraceLoggingBinary(pValue, cbValue, [Name, ...]):

    Fügt ein Feld mit Binären Daten hinzu.

  • TraceLoggingBinaryEx(pValue, cbValue, outType, [Name, ...]):

    Fügt ein Feld mit Binärdaten mit dem formatierungshinweis hinzu, der durch outTypeangegeben wird.

  • TraceLoggingBinaryBuffer(pValue, StructType, [Name, ...]):

    Fügt ein Feld mit Binären Daten hinzu. pValue muss ein Nicht-NULL-Zeiger auf eine StructType Struktur sein. pValue->Buffer muss zu Beginn der Daten zeigen und pValue->Length die Anzahl der Bytes sein, die in das Feld eingeschlossen werden sollen.

  • TraceLoggingBinaryBufferEx(pValue, StructType, outType, name, description, tag):

    Fügt ein Feld mit Binärdaten mit dem formatierungshinweis hinzu, der durch outTypeangegeben wird. pValue muss ein Nicht-NULL-Zeiger auf eine StructType Struktur sein. pValue->Buffer muss zu Beginn der Daten zeigen und pValue->Length die Anzahl der Bytes sein, die in das Feld eingeschlossen werden sollen.

  • TraceLoggingCustom(pValue, cbValue, protocol, bSchema, cbSchema, [name, ...]):

    Fügt ein Feld mit binären Daten hinzu, die gemäß einem Serialisierungsprotokoll serialisiert wurden. Kompilierungszeitkonstantendecodierungsinformationen werden zusammen mit dem Ereignis eingeschlossen, um die Deserialisierung durch den Ereignisdecoder zu ermöglichen.

Strukturen

Sie können das TraceLoggingStruct(fieldCount, name, [...]) Makro verwenden, um eine benannte Struktur (Gruppe von Feldern) zu erstellen. Der parameter fieldCount gibt an, wie viele der nachfolgenden Felder als Teil der Struktur gezählt werden sollen. Strukturen können geschachtelt werden, in diesem Fall zählt jede geschachtelte Struktur und ihre enthaltenen Felder als einzelnes Feld zum Definieren der übergeordneten Struktur.

Felder

Sie können ein Feld erstellen, das ein Array von skalaren (einzelnen) Werten enthält. Sie fügen beispielsweise ein Array von GUIDs als einzelnes Feld in Ihrem Ereignis hinzu.

Anmerkung

Während das TraceLogging-Protokoll Arrays aller Typen unterstützt, stellt TraceLoggingProvider.h nur Wrappermakros für Arrays einfacher Werte bereit, z. B. Makros für Arrays von INT32 und GUID, es stellt jedoch keine Makros für Arrays von Zeichenfolgen oder Arrays von Strukturen bereit. Es ist möglich, Ereignisse mit Arrays komplexer Werte zu erstellen, indem Sie die Daten in einen Puffer marshallen und dann die unten beschriebenen TraceLoggingPacked Makros verwenden.

TraceLogging unterstützt Arrays mit fester Länge und Variabler Länge.

  • Verwenden Sie das Array Makro in Fällen, in denen die Arraylänge zur Kompilierungszeit nicht bekannt ist und bei jedem Generieren des Ereignisses unterschiedlich sein kann.
  • Verwenden Sie das makro FixedArray in Fällen, in denen die Arraylänge zur Kompilierungszeit bekannt ist (d. h. wenn die Arraylänge eine Konstante ist). Dadurch wird dem Ereignisverbraucher mitgeteilt, dass alle Ereignisse mit einem bestimmten Ereignisnamen dieselbe Anzahl von Elementen im Arrayfeld aufweisen.

Alle Arraymakros erfordern die pValues und cValues Parameter anzugeben, wobei pValues auf den Anfang des Arrayinhalts zeigen und cValues auf die Anzahl der Elemente im Array festgelegt. pValues- darf nur NULL sein, wenn cValues 0 ist.

Alle Arraymakros akzeptieren optional Namen, Beschreibung, und Tag Parameter, wie für die Skalar-Makros beschrieben. Wenn Name nicht angegeben ist, wird der Feldname aus dem Präprozessortext pValuesbestimmt. Wenn Beschreibung nicht angegeben ist, wird die Feldbeschreibung "". Wenn Tag nicht angegeben ist, wird das Feldtag 0.

Anmerkung

Um sicherzustellen, dass ETW Ihre Ereignisse nicht abgibt, vermeiden Sie das Erstellen von Ereignissen mit großen Arrays. ETW unterstützt keine Ereignisse, die größer als 64 KB sind. Alle derartigen Ereignisse werden von ETW im Hintergrund gelöscht. Darüber hinaus werden Ereignisse, die größer als die BufferSize- der Consumersitzung sind, ebenfalls von ETW gelöscht. Die Ereignisgröße basiert auf der Summe der Kopfzeilen, Metadaten (Anbieter, Ereignis und Feldnamen) und Daten (Feldwerte).

  • TraceLoggingInt8Array(pValues, cValues, [Name, ...])
  • TraceLoggingInt8FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingUInt8Array(pValues, cValues, [Name, ...])
  • TraceLoggingUInt8FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingInt16Array(pValues, cValues, [Name, ...])
  • TraceLoggingInt16FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingUInt16Array(pValues, cValues, [Name, ...])
  • TraceLoggingUInt16FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingInt32Array(pValues, cValues, [Name, ...])
  • TraceLoggingInt32FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingUInt32Array(pValues, cValues, [Name, ...])
  • TraceLoggingUInt32FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingInt64Array(pValues, cValues, [Name, ...])
  • TraceLoggingInt64FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingUInt64Array(pValues, cValues, [Name, ...])
  • TraceLoggingUInt64FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingIntPtrArray(pValues, cValues, [Name, ...])
  • TraceLoggingIntPtrFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingUIntPtrArray(pValues, cValues, [Name, ...])
  • TraceLoggingUIntPtrFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingLongArray(pValues, cValues, [Name, ...])
  • TraceLoggingLongFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingULongArray(pValues, cValues, [Name, ...])
  • TraceLoggingULongFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexInt8Array(pValues, cValues, [Name, ...])
  • TraceLoggingHexInt8FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexUInt8Array(pValues, cValues, [Name, ...])
  • TraceLoggingHexUInt8FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexInt16Array(pValues, cValues, [Name, ...])
  • TraceLoggingHexInt16FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexUInt16Array(pValues, cValues, [Name, ...])
  • TraceLoggingHexUInt16FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexInt32Array(pValues, cValues, [Name, ...])
  • TraceLoggingHexInt32FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexUInt32Array(pValues, cValues, [Name, ...])
  • TraceLoggingHexUInt32FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexInt64Array(pValues, cValues, [Name, ...])
  • TraceLoggingHexInt64FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexUInt64Array(pValues, cValues, [Name, ...])
  • TraceLoggingHexUInt64FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexIntPtrArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexIntPtrFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexUIntPtrArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexUIntPtrFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexLongArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexLongFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexULongArray(pValues, cValues, [Name, ...])
  • TraceLoggingHexULongFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingFloat32Array(pValues, cValues, [Name, ...])
  • TraceLoggingFloat32FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingFloat64Array(pValues, cValues, [Name, ...])
  • TraceLoggingFloat64FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingBooleanArray(pValues, cValues, [Name, ...])
  • TraceLoggingBooleanFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingBoolArray(pValues, cValues, [Name, ...])
  • TraceLoggingBoolFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingCharArray(pValues, cValues, [Name, ...])
  • TraceLoggingCharFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingChar16Array(pValues, cValues, [Name, ...])
  • TraceLoggingChar16FixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingWCharArray(pValues, cValues, [Name, ...])
  • TraceLoggingWCharFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingPointerArray(pValues, cValues, [Name, ...])
  • TraceLoggingPointerFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingCodePointerArray(pValues, cValues, [Name, ...])
  • TraceLoggingCodePointerFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingFileTimeArray(pValues, cValues, [Name, ...])
  • TraceLoggingFileTimeFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingFileTimeUtcArray(pValues, cValues, [Name, ...])
  • TraceLoggingFileTimeUtcFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingSystemTimeArray(pValues, cValues, [Name, ...])
  • TraceLoggingSystemTimeFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingSystemTimeUtcArray(pValues, cValues, [Name, ...])
  • TraceLoggingSystemTimeUtcFixedArray(pValues, cValues, [Name, ...])
  • TraceLoggingGuidArray(pValues, cValues, [Name, ...])
  • TraceLoggingGuidFixedArray(pValues, cValues, [Name, ...])

Verpackte Makros

TraceLoggingProvider.h stellt nur Feldmakros für blittbare Feldtypen bereit, d. h. Felder, bei denen jedes Feldmakro einem einzelnen Feld entspricht, und einem einzelnen zusammenhängenden Speicherbereich mit dem Wert des Felds.

TraceLoggingProvider.h bietet keine direkte Unterstützung für komplexere Fälle wie:

  • Protokollierung eines Arrays eines Variablenlängentyps, z. B. eines Arrays von Zeichenfolgen.
  • Protokollieren eines Arrays von Strukturen.
  • Übergeben mehrerer Felder über einen einzigen Puffer an ETW, um den Aufwand für die Ereignisprotokollierung zu reduzieren.

Um diese Szenarien zu unterstützen, definiert TraceLoggingProvider.h mehrere TraceLoggingPacked Makros, mit denen Sie die Ereignisdefinition (Metadaten) und Feldwerte (Daten) des Ereignisses direkt bearbeiten können.

Warnung

Die TraceLoggingPacked Makros sind schwierig zu verwenden, und erfordern ein gutes Verständnis dafür, wie TraceLogging-Ereignisse erstellt werden. Wenn sie falsch verwendet werden, führen sie zu beschädigten Ereignissen, die nicht ordnungsgemäß decodiert werden.

Ausführliche Informationen zur Verwendung dieser Makros finden Sie in den Kommentaren im Header "TraceLoggingProvider.h".

  • TraceLoggingPackedField(pValue, cbValue, inType, [name, description, tags]):

    Fügt Felddaten (pValue, cbValue) und Feldmetadaten (Name, inType) hinzu.

  • TraceLoggingPackedFieldEx(pValue, cbValue, inType, outType, [name, ...]):

    Fügt Felddaten (pValue, cbValue) und Feldmetadaten (Name, inType) zusammen mit einem Formatierungshinweis (outType) hinzu.

  • TraceLoggingPackedMetadata(inType, [Name, ...]):

    Fügt Feldmetadaten (Name, inType) hinzu, ohne Felddaten hinzuzufügen. Entsprechende Felddaten müssen über TraceLoggingPackedData hinzugefügt werden.

  • TraceLoggingPackedMetadataEx(inType, outType, [Name, ...]):

    Fügt Feldmetadaten (Name, InType) und einen Formatierungshinweis (outType) hinzu, ohne Felddaten hinzuzufügen. Entsprechende Felddaten müssen über TraceLoggingPackedData hinzugefügt werden.

  • TraceLoggingPackedStruct(fieldCount, name, [...]):

    Fügt Feldmetadaten (Name, fieldCount) für eine Struktur hinzu.

  • TraceLoggingPackedStructArray(fieldCount, [name, ...]):

    Fügt Feldmetadaten (Name, FieldCount) für ein Array mit variabler Länge der Struktur hinzu. Die Arraylänge muss über TraceLoggingPackedData angegeben werden.

  • TraceLoggingPackedData(pValue, cbValue):

    Fügt Felddaten zu einem Ereignis hinzu, ohne Feldmetadaten hinzuzufügen. Entsprechende Metadaten müssen über die Metadatenmakros hinzugefügt werden.

  • TraceLoggingPackedDataEx(pValue, cbValue, dataDescType):

    Fügt Felddaten zu einem Ereignis hinzu, ohne Feldmetadaten hinzuzufügen, wobei ein bestimmter Type im EVENT_DATA_DESCRIPTOR für die Daten verwendet wird. Entsprechende Metadaten müssen über die Metadatenmakros hinzugefügt werden.