TraceLogging-Wrappermakros

  • Artikel

Die Makros TraceLoggingWrite und TraceLoggingWriteActivity geben TraceLogging-Ereignisse aus, die gemäß den Makroparametern konfiguriert sind. Jedes dieser Makros akzeptiert einen Satz von erforderlichen Parametern, 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.

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 g_hProvider sind und "MyEvent1" die erforderlichen Parameter. Sie geben den Anbieter an, der für das Ereignis verwendet werden soll, und den Namen des Ereignisses. Jeder der verbleibenden Parameter ist ein Wrappermakro. Die TraceLoggingLevel Parameter und TraceLoggingKeyword konfigurieren das Ereignis. Die TraceLoggingString Parameter und TraceLoggingHResult fügen dem Ereignis Felder hinzu.

Ereigniskonfigurationsmakros

Das Ereignis wird mit den folgenden Makros konfiguriert.

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

  • TraceLoggingLevel legt die Ereignisebene fest. Die Ebene ist ein 8-Bit-Wert, der den Schweregrad des Ereignisses angibt. Die 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. Die Ebene ist ein wichtiger Bestandteil des ETW-Ereignisroutings und der -Filterung, sodass alle Ereignisse eine aussagekräftige Nicht-Null-Ebene aufweisen sollten.
  • TraceLoggingKeyword legt die Schlüsselwort (keyword) des Ereignisses fest. Ein Schlüsselwort (keyword) ist ein 64-Bit-Wert, wobei jedes Bit eine Kategorie angibt, zu der das Ereignis gehört. Die niedrigen 48 Bits der Schlüsselwort (keyword) werden vom Besitzer des Anbieters definiert, während die hohen 16 Bits der Schlüsselwort (keyword) von Microsoft definiert werden. Sie können beispielsweise entscheiden, dass alle Anbieter mit dem Namen "MyCompany.MyComponent" Schlüsselwort (keyword) 0x1 verwenden, um "Netzwerk" zu bedeuten. Wenn nicht angegeben, wird das Ereignis standardmäßig auf Schlüsselwort (keyword) 0x0 (None) festgelegt. Das Schlüsselwort ist ein wichtiger Bestandteil des ETW-Ereignisroutings und der -Filterung, sodass alle Ereignisse einen aussagekräftigen Schlüsselwort (keyword) ungleich Null aufweisen sollten.
  • TraceLoggingOpcode legt den Opcode des Ereignisses fest. Opcode ist ein 8-Bit-Wert, der eine 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 das Ereignis standardmäßig auf opcode 0 (WINEVENT_OPCODE_INFO) festgelegt, was angibt, dass keine spezielle Semantik erforderlich ist.
  • TraceLoggingChannel legt den Kanal des Ereignisses fest. 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. Ein Anbieter kann beispielsweise Tagbit 0x1000000 definieren, um anzugeben, dass das Ereignis möglicherweise personenbezogene Informationen enthält und von anbieterspezifischen Ereignisverarbeitungstools eine besondere Behandlung erhalten sollte. Wenn nicht angegeben, ist 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 (PDB) Ihrer Komponente aufgezeichnet. Wenn nicht angegeben, ist die Beschreibung standardmäßig auf ""festgelegt.
  • TraceLoggingCustomAttribute fügt den Debugsymbolen (PDB) der Komponente eine Schlüssel-Wert-Anmerkung hinzu.

Feldmakros

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

Die meisten Feld wrapper-Makros 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 Feld wrappermakros verwenden einen einzelnen Parameter, um den Wert anzugeben, aber einige Makros erfordern 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 pszValue angegeben. In diesem Fall handelt es sich um einen Zeiger auf eine 0-endende Zeichenzeichenfolge, die in das Feld eingeschlossen werden soll. 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 von cchValue-Zeichen , die in das Feld eingeschlossen werden sollen. pchValue kann nur NULL sein, wenn cchValue 0 ist.
    • In einigen Fällen wird der Feldwert als pValue mit einer automatisch ermittelten 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 ist möglicherweise nicht NULL.
    • In einigen Fällen wird der Feldwert als pValue mit einem cbValue-Parameter angegeben, um die Größe (in Bytes) der Daten anzugeben, die in das Feld eingeschlossen werden sollen. pValue darf nur NULL sein, wenn cbValue 0 ist.
  • Namen: Ein Zeichenfolgenliteral (Kompilierzeitkonstante) mit dem Namen, der für das Feld verwendet werden soll. Für die meisten Feld wrappermakros ist kein Namensparameter erforderlich. Wenn Sie den parameter name weglassen, wird der Name des Felds basierend auf dem Präprozessortext des Makrowerts, pszValue, pchValue oder pValue-Parameter bestimmt. TraceLoggingInt32(x[4] + y) entspricht beispielsweise TraceLoggingInt32(x[4] + y, "x[4] + y"). Beide würden dem -Ereignis ein Feld mit dem Namen "x[4] + y" hinzufügen, mit einem Wert, der durch Auswertung des Ausdrucks x[4] + ybestimmt wird.
  • Beschreibung: Ein Zeichenfolgenliteral (Kompilierzeitkonstante) mit einer Beschreibung, die für das Feld verwendet werden soll. Dies wird meist als praktischer Ort zum Platzieren eines Kommentars für das Feld verwendet, aber die Beschreibung wird auch als Anmerkung in den Debugsymbolen (PDB) der Komponente aufgezeichnet. Die Angabe einer Beschreibung ist optional. Wenn der description-Parameter ausgelassen wird, wird die Beschreibung des Felds standardmäßig auf verwendet "".
  • Etikett: Eine 28-Bit-Ganzzahl (Kompilierzeitkonstante) mit vom Anbieter definierter Semantik. Ein Anbieter kann beispielsweise tag-0x2 definieren, um anzugeben, dass das Feld eine Telefonnummer enthält und von anbieterspezifischen Ereignisverarbeitungstools eine besondere Behandlung erhalten sollte. Wenn der Tagparameter ausgelassen wird, wird das Tag des Felds standardmäßig auf 0 festgelegt.

Beispielsweise haben die folgenden Wrappermakroaufrufe alle die gleiche 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 aus dem 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(value, [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 (ganzzahlige Vorzeichen mit der gleichen Größe wie ein Zeiger) hinzu.

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

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

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

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

  • 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 hexadezimalen Formatierungshinweis hinzu.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Fügt ein Feld mit einem INT_PTR Wert mit einem hexadezimalen Formatierungshinweis hinzu.

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

    Fügt ein Feld mit einem UINT_PTR-Wert mit einem hexadezimalen Formatierungshinweis hinzu.

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

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

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

    Fügt ein Feld mit einem ULONG-Wert mit einem hexadezimalen Formatierungshinweis 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 (Win32 BOOLEAN oder C++ ) boolhinzu.

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

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

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

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

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

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

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

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

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

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

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

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

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

    Fügt ein Feld mit einem INT32-Wert mit einem Formatierungshinweis für die Prozess-ID hinzu.

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

    Fügt ein Feld mit einem INT32-Wert mit einem Thread-ID-Formatierungshinweis 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 Binärwert von 16 Byte 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-Fehlercode-Formatierungshinweis 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 in C-Code muss der value Parameter ein lvalue-Ausdruck sein.

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

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

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

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

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

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

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

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

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

    Fügt ein Feld mit einer 0-Zeichenfolge hinzu char (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-Zeichenfolge char 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 (in der Regel als Codepage 1252 behandelt). pchValue kann nur NULL sein, wenn cchValue 0 ist.

  • TraceLoggingCountedUtf8String(pchValue, cchValue, [name, description, 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 müssen gültig sein).

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

    Fügt ein Feld mit Binärdaten hinzu.

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

    Fügt ein Feld mit Binärdaten mit dem durch outTypeangegebenen Formatierungshinweis hinzu.

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

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

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

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

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

    Fügt ein Feld mit Binärdaten hinzu, das gemäß einem Serialisierungsprotokoll serialisiert wurde. Kompilierzeitkonstante Decodierungsinformationen werden zusammen mit dem Ereignis eingeschlossen, um die Deserialisierung durch den Ereignisdecoder zuzulassen.

Strukturen

Sie können das Makro TraceLoggingStruct(fieldCount, name, [...]) 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 sein. In diesem Fall zählt jede geschachtelte Struktur und ihre enthaltenen Felder als ein einzelnes Feld, um die übergeordnete Struktur zu definieren.

Arrays

Sie können ein Feld erstellen, das ein Array skalarer (einzelner) Werte enthält. Beispielsweise fügen Sie in Ihrem Ereignis ein Array von GUIDs als einzelnes Feld hinzu.

Hinweis

Während das TraceLogging-Protokoll Arrays aller Typen unterstützt, stellt TraceLoggingProvider.h nur Wrappermakros für Arrays mit einfachen Werten bereit, z. B. stellt es Makros für Arrays von INT32 und GUID bereit, aber keine Makros für Arrays von String oder Arrays von Strukturen. Es ist möglich, Ereignisse mit Arrays mit komplexen Werten zu erstellen, indem Sie die Daten in einen Puffer marshallen und dann die TraceLoggingPacked unten beschriebenen 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 Kompilierzeit nicht bekannt ist und sich bei jeder Ereignisgenerierung möglicherweise unterscheidet.
  • Verwenden Sie das FixedArray Makro in Fällen, in denen die Arraylänge zur Kompilierzeit bekannt ist (d. h. wenn die Arraylänge eine Konstante ist). Dadurch wird dem Ereignis-Consumer mitgeteilt, dass alle Ereignisse mit einem bestimmten Ereignisnamen die gleiche Anzahl von Elementen im Arrayfeld aufweisen.

Für alle Arraymakros müssen die Parameter pValues und cValues angegeben werden, wobei pValues auf den Anfang des Arrayinhalts und cValues auf die Anzahl der Elemente im Array festgelegt ist. pValues darf nur NULL sein, wenn cValues 0 ist.

Alle Arraymakros akzeptieren optional namen-, beschreibungs- und tagparameter , wie für die Skalarmakros beschrieben. Wenn name nicht angegeben ist, wird der Feldname aus dem Präprozessortext von pValues bestimmt. Wenn die Beschreibung nicht angegeben ist, lautet ""die Feldbeschreibung . Wenn das Tag nicht angegeben ist, lautet 0das Feldtag .

Hinweis

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. Solche Ereignisse werden von ETW automatisch gelöscht. Darüber hinaus werden Ereignisse, die größer als die BufferSize-Sitzung der Consumersitzung sind, auch von ETW gelöscht. Die Ereignisgröße basiert auf der Summe der Header, Metadaten (Anbieter-, Ereignis- und Feldnamen) und Daten (Feldwerte) des Ereignisses.

  • 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, ...])

Gepackte Makros

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

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

  • Protokollierung eines Arrays mit einem Typ mit variabler Länge, z. B. ein Array von Zeichenfolgen.
  • Protokollierung eines Arrays von Strukturen.
  • Übergeben mehrerer Felder an ETW über einen einzelnen Puffer, um den Aufwand für die Ereignisprotokollierung zu reduzieren.

Zur Unterstützung dieser Szenarien definiert TraceLoggingProvider.h mehrere TraceLoggingPacked Makros, mit denen Sie die Ereignisdefinition (Metadaten) und Die Feldwerte (Daten) des Ereignisses direkt bearbeiten können.

Warnung

Die TraceLoggingPacked Makros sind bei der ordnungsgemäßen Verwendung schwierig und erfordern ein gutes Verständnis dafür, wie TraceLogging-Ereignisse erstellt werden. Bei falscher Verwendung 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, Beschreibung, 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 Strukturarray mit variabler Länge hinzu. Die Arraylänge muss über TraceLoggingPackedData angegeben werden.

  • TraceLoggingPackedData(pValue, cbValue):

    Fügt einem Ereignis Felddaten 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 bestimmtes Type im EVENT_DATA_DESCRIPTOR für die Daten verwendet wird. Entsprechende Metadaten müssen über die Metadatenmakros hinzugefügt werden.