訓練
學習路徑
Implement finance and operations apps - Training
Plan and design your project methodology to successfully implement finance and operations apps with FastTrack services, data management and more.
TraceLoggingWrite和TraceLoggingWriteActivity宏會根據巨集引數發出 TraceLogging 事件。 每個宏都接受一組必要的參數,後面接著最多 99 個選擇性參數。 每個選擇性參數都會設定事件,或將欄位加入事件。 每個選擇性參數都必須是此頁面所述的 TraceLogging 包裝函式宏之一。
例如:
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.
在此範例中, g_hProvider
和 "MyEvent1"
是必要參數。
他們會指定要用於事件和事件名稱的提供者。 其餘每個參數都是包裝函式宏。 和 TraceLoggingKeyword
參數會 TraceLoggingLevel
設定 事件。 和 TraceLoggingHResult
參數會將 TraceLoggingString
欄位新增至 事件。
下列宏會設定 事件。
如果未在 TraceLoggingWrite中提供特定的組態宏,則會使用該事件的預設值。 例如,如果事件沒有使用 TraceLoggingLevel 參數,則事件會使用預設層級 5 (VERBOSE) 。
<winmeta.h>
。 如果未指定,事件預設為層級 5 (VERBOSE) 。
Level 是 ETW 事件路由和篩選的重要部分,因此所有事件都應該有有意義的非零層級。""
。TraceLogging 支援許多包裝函式宏,可將欄位新增至事件。 每個欄位都是名稱/值組。 例如, TraceLoggingInt32(argc, "ArgCount")
會新增名為 「ArgCount」 且值為 argc
的 INT32 欄位。
大部分欄位包裝函式宏都接受類似的參數:
""
。TraceLoggingInt32(x[4] + y)
相當於 TraceLoggingInt32(x[4] + y, "x[4] + y")
。 兩者都會使用評估運算式 x[4] + y
所決定的值,將名為 "x[4] + y"
的欄位新增至 事件。""
。例如,下列包裝函式宏調用都具有相同的效果:
TraceLoggingInt32(argc)
TraceLoggingInt32(argc, "argc")
TraceLoggingInt32(argc, "argc", "")
TraceLoggingInt32(argc, "argc", "", 0)
TraceLoggingValue (value, [name, ...]) :
加入具有從 value 參數型別自動推斷的欄位。 僅 (C++)
TraceLoggingInt8 (value, [name, ...]) :
加入具有 INT8 值的欄位。
TraceLoggingUInt8 (value, [name, ...]) :
新增具有 UINT8 值的欄位。
TraceLoggingInt16 (value, [name, ...]) :
加入具有 INT16 值的欄位。
TraceLoggingUInt16 (value, [name, ...]) :
新增具有 UINT16 值的欄位。
TraceLoggingInt32 (value, [name, ...]) :
加入具有 INT32 值的欄位。
TraceLoggingUInt32 (value, [name, ...]) :
新增具有 UINT32 值的欄位。
TraceLoggingInt64 (value, [name, ...]) :
新增具有 INT64 值的欄位。
TraceLoggingUInt64 (value, [name, ...]) :
新增具有 UINT64 值的欄位。
TraceLoggingIntPtr (value, [name, ...]) :
將具有INT_PTR值的欄位加入 (帶正負號的整數,其大小與指標) 相同。
TraceLoggingUIntPtr (value, [name, ...]) :
新增具有UINT_PTR值的欄位, (不帶正負號的整數,其大小與指標) 相同。
TraceLoggingLong (value, [name, ...]) :
在 Windows 平臺上新增具有 LONG 值的欄位 (帶正負號的 long int,) 32 位。
TraceLoggingULong (value, [name, ...]) :
在 Windows 平臺上新增具有 ULONG 值的欄位 (未帶正負號的 long int,32 位) 。
TraceLoggingHexInt8 (value, [name, ...]) :
使用十六進位格式提示新增具有 INT8 值的欄位。
TraceLoggingHexUInt8 (value, [name, ...]) :
使用十六進位格式提示新增具有 UINT8 值的欄位。
TraceLoggingHexInt16 (value, [name, ...]) :
使用十六進位格式提示新增具有 INT16 值的欄位。
TraceLoggingHexUInt16 (value, [name, ...]) :
使用十六進位格式提示新增具有 UINT16 值的欄位。
TraceLoggingHexInt32 (value, [name, ...]) :
使用十六進位格式提示新增具有 INT32 值的欄位。
TraceLoggingHexUInt32 (value, [name, ...]) :
使用十六進位格式提示新增具有 UINT32 值的欄位。
TraceLoggingHexInt64 (value, [name, ...]) :
使用十六進位格式提示新增具有 INT64 值的欄位。
TraceLoggingHexUInt64 (value, [name, ...]) :
使用十六進位格式提示新增具有 UINT64 值的欄位。
TraceLoggingHexIntPtr (value, [name, ...]) :
使用十六進位格式提示,新增具有INT_PTR值的欄位。
TraceLoggingHexUIntPtr (value, [name, ...]) :
使用十六進位格式提示新增具有UINT_PTR值的欄位。
TraceLoggingHexLong (value, [name, ...]) :
使用十六進位格式提示新增具有 LONG 值的欄位。
TraceLoggingHexULong (value, [name, ...]) :
使用十六進位格式提示新增具有 ULONG 值的欄位。
TraceLoggingFloat32 (value, [name, ...]) :
新增具有 FLOAT (32 位浮點數) 值的欄位。
TraceLoggingFloat64 (value, [name, ...]) :
新增具有 DOUBLE (64 位浮點數) 值的欄位。
TraceLoggingBoolean (value, [name, ...]) :
(Win32 BOOLEAN
或 C++ bool
) 新增具有 8 位布林值的欄位。
TraceLoggingBool (value, [name, ...]) :
(Win32) 新增具有 32 BOOL
位布林值的欄位。
TraceLoggingChar (value, [name, ...]) :
新增具有 char
值 (8 位整數且字串格式提示的欄位,通常視為字碼頁 1252) 。
TraceLoggingChar16 (value, [name, ...]) :
新增具有值 (16 位整數且字串格式提示的欄位 char16_t
,通常視為 UCS-2) 。
TraceLoggingWChar (value, [name, ...]) :
在 Windows 平臺上) 新增具有值 (的 char16_t
欄位 wchar_t
。
TraceLoggingPointer (value, [name, ...]) :
新增具有 void*
值 (具有十六進位格式提示) 的指標大小值欄位。
TraceLoggingCodePointer (value, [name, ...]) :
使用程式碼指標格式提示) ,新增具有值 (指標大小的欄位 void*
。
TraceLoggingPid (value, [name, ...]) :
使用進程識別碼格式提示,新增具有 INT32 值的欄位。
TraceLoggingTid (value, [name, ...]) :
新增具有具有線程識別碼格式提示之 INT32 值的欄位。
TraceLoggingIPv4Address (value, [name, ...]) :
使用 IPv4 格式提示新增具有 UINT32 值的欄位, (網路位元組順序) 。
TraceLoggingIPv6Address (pValue, [name, ...]) :
使用 IPv6 格式提示新增具有 16 位元組二進位值的欄位。
TraceLoggingPort (value, [name, ...]) :
將具有 UINT16 值的欄位新增為 IP 埠格式提示, (網路位元組順序) 。
TraceLoggingSocketAddress (pValue, cbValue, [name, ...]) :
加入具有 SOCKADDR 值的欄位。
TraceLoggingWinError (value, [name, ...]) :
使用 Win32 錯誤碼格式提示新增具有 UINT32 值的欄位。
TraceLoggingNTStatus (value, [name, ...]) :
使用 WINNT 錯誤碼格式提示,新增具有 NTSTATUS (LONG) 值的欄位。
TraceLoggingHResult (value, [name, ...]) :
使用 Windows HRESULT 格式提示新增具有 HRESULT (LONG) 值的欄位。
TraceLoggingFileTime (value, [name, ...]) :
加入具有 FILETIME 值的欄位。 在 C 程式碼中使用時, value
參數必須是左值運算式。
TraceLoggingFileTimeUtc (value, [name, ...]) :
使用 UTC 時區格式提示,新增具有 FILETIME 值的欄位。 在 C 程式碼中使用時, value
參數必須是左值運算式。
TraceLoggingSystemTime (value, [name, ...]) :
加入具有 SYSTEMTIME 值的欄位。
在 C 程式碼中使用時, value
參數必須是左值運算式。
TraceLoggingSystemTimeUtc (value, [name, ...]) :
使用 UTC 時區格式提示新增具有 SYSTEMTIME 值的欄位。 在 C 程式碼中使用時, value
參數必須是左值運算式。
TraceLoggingGuid (value, [name, ...]) :
加入具有 GUID 值的欄位。
在 C 程式碼中使用時, value
參數必須是左值運算式。
TraceLoggingString (pszValue, [name, ...]) :
新增具有 0 終止 char
字串的欄位, (通常視為字碼頁 1252) 。 如果 pszValue 為 Null,則會使用空字串 ""
做為域值。
TraceLoggingUtf8String (pszValue, [name, ...]) :
使用 UTF-8 格式提示,新增具有 0 終止 char
字串的欄位。
如果 pszValue 為 Null,則會使用空字串 ""
做為域值。
TraceLoggingString16 (pszValue, [name, ...]) :
(UTF-16) 新增具有 0 終止 char16_t
字串的欄位。 如果 pszValue 為 Null,則會使用空字串 u""
做為域值。
TraceLoggingWideString (pszValue, [name, ...]) :
在 Windows) 上新增具有 0 終止 wchar_t
字串的欄位, (UTF-16。 如果 pszValue 為 Null,則會使用空字串 L""
做為域值。
TraceLoggingCountedString (pchValue, cchValue, [name, ...]) :
新增具有計算 char
字串的欄位, (通常視為字碼頁 1252) 。 只有在 cchValue 為 0 時,pchValue 才可為 Null。
TraceLoggingCountedUtf8String (pchValue, cchValue, [name, description, tag]) :
新增具有 UTF-8 格式提示之 char
計數位符串的欄位。
只有在 cchValue 為 0 時,pchValue 才可為 Null。
TraceLoggingCountedString16 (pchValue, cchValue, [name, ...]) :
新增具有計算 char16_t
字串的欄位, (UTF-16) 。 只有在 cchValue 為 0 時,pchValue 才可為 Null。
TraceLoggingCountedWideString (pchValue, cchValue, [name, description, tag]) :
在 Windows) 上新增具有計算 wchar_t
字串的欄位 (UTF-16。 只有在 cchValue 為 0 時,pchValue 才可為 Null。
TraceLoggingAnsiString (pValue, [name, ...]) :
加入具有 ANSI_STRING 值的欄位。 pValue 指標不得為 Null。
TraceLoggingUnicodeString (pValue, [name, ...]) :
加入具有 UNICODE_STRING 值的欄位。 pValue 指標不得為 Null。
TraceLoggingSid (pValue, [name, ...]) :
加入具有 SID 值的欄位。 pValue 指標不得為 Null,而且必須指向正確初始化的 SID (Revision 和 SubAuthorityCount 必須是有效的) 。
TraceLoggingBinary (pValue, cbValue, [name, ...]) :
加入具有二進位資料的欄位。
TraceLoggingBinaryEx (pValue, cbValue, outType, [name, ...]) :
使用 所 outType
指定的格式提示,加入具有二進位資料的欄位。
TraceLoggingBinaryBuffer (pValue, StructType, [name, ...]) :
加入具有二進位資料的欄位。
pValue
必須是結構的非 Null 指標 StructType
。
pValue->Buffer
必須指向資料開頭,而且 pValue->Length
必須是欄位中要包含的資料位元組數目。
TraceLoggingBinaryBufferEx (pValue, StructType, outType, name, description, tag) :
使用 所 outType
指定的格式提示,加入具有二進位資料的欄位。
pValue
必須是結構的非 Null 指標 StructType
。
pValue->Buffer
必須指向資料開頭,而且 pValue->Length
必須是欄位中要包含的資料位元組數目。
TraceLoggingCustom (pValue, cbValue, protocol, bSchema, cbSchema, [name, ...]) :
加入欄位,其中包含已根據序列化通訊協定序列化的二進位資料。 編譯時間常數解碼資訊會連同 事件一起包含,以允許事件解碼器還原序列化。
您可以使用 TraceLoggingStruct (fieldCount, name, [...]) 宏, (欄位群組) 建立具名結構。 fieldCount參數會指出應計算多少個後續欄位作為 結構的一部分。 結構可以是巢狀結構,在此情況下,每個巢狀結構及其包含的欄位都會計算為單一欄位,以便定義父結構。
您可以建立包含純量陣列的欄位, (單一) 值。 例如,您會在事件中新增 GUID 陣列做為單一欄位。
注意
雖然 TraceLogging 通訊協定支援所有類型的陣列,但 TraceLoggingProvider.h 只提供簡單值陣列的包裝函式宏,例如它會為 INT32 和 GUID 的陣列提供宏,但不會提供字串陣列或結構陣列的宏。 您可以使用複雜值的陣列建立事件,方法是將資料封送處理至緩衝區,然後使用 TraceLoggingPacked
以下所述的宏。
TraceLogging 支援固定長度和可變長度陣列。
Array
在編譯時期不知道陣列長度,而且每次產生事件時可能不同時,請使用 宏。FixedArray
在編譯時期已知陣列長度 (即當陣列長度是常數) 時,請使用 宏。 這會與事件取用者通訊,具有特定事件名稱的所有事件在陣列欄位中會有相同數目的專案。所有陣列宏都需要指定pValues 和 cValues參數,而pValues指向陣列內容的開頭,並將 cValues設定為數組中的專案數。 只有在 cValues 為 0 時 ,pValues 才能是 Null。
所有陣列宏都會選擇性地接受純量宏所描述 的名稱、 描述和 標記 參數。 如果未指定 name ,則會從 pValues的預處理器文字決定功能變數名稱。 如果未指定 描述 ,欄位描述會是 ""
。 如果未指定 tag ,欄位標籤會是 0
。
注意
為了確保 ETW 不會卸載您的事件,請避免使用大型陣列建立事件。 ETW 不支援大於 64KB 的事件。 ETW 會以無訊息方式卸載任何這類事件。 此外,ETW 也會卸載大於取用者會話 之 BufferSize 的事件。 事件大小是根據事件標頭、中繼資料 (提供者、事件和功能變數名稱的總和) ,以及 (域值) 。
TraceLoggingProvider.h 只提供 blittable 欄位類型的欄位宏,也就是每個欄位宏對應至單一欄位的欄位,以及具有欄位值的單一連續記憶體區域。
TraceLoggingProvider.h 不提供更複雜案例的直接支援,例如:
為了支援這些案例,TraceLoggingProvider.h 會定義數 TraceLoggingPacked
個宏,讓您直接操作事件定義 (中繼資料) 和域值, (事件的資料) 。
警告
宏 TraceLoggingPacked
很難正確使用,而且需要充分瞭解 TraceLogging 事件的建立方式。 如果使用不正確,則會導致未正確解碼的損毀事件。
如需使用這些宏的詳細資訊,請參閱 TraceLoggingProvider.h 標頭中的批註。
TraceLoggingPackedField (pValue, cbValue, inType, [name, description, tags]) :
將欄位資料 (pValue、cbValue) 和欄位中繼資料 (名稱加入 inType) 。
TraceLoggingPackedFieldEx (pValue, cbValue, inType, outType, [name, ...]) :
將欄位資料 (pValue、cbValue) 和欄位中繼資料 (名稱加入 inType) ,以及 outType (outType) 的格式提示。
TraceLoggingPackedMetadata (inType, [name, ...]) :
新增欄位中繼資料 (名稱,inType) 而不新增欄位資料。 必須透過 TraceLoggingPackedData 新增對應的欄位資料。
TraceLoggingPackedMetadataEx (inType, outType, [name, ...]) :
新增欄位中繼資料 (名稱、inType) 和格式化提示, (outType) 而不新增欄位資料。 必須透過 TraceLoggingPackedData 新增對應的欄位資料。
TraceLoggingPackedStruct (fieldCount, name, [...]) :
新增結構 (名稱、fieldCount) 欄位中繼資料。
TraceLoggingPackedStructArray (fieldCount, [name, ...]) :
為結構可變長度陣列新增欄位中繼資料 (名稱、fieldCount) 。 陣列長度必須透過 TraceLoggingPackedData 來指定。
TraceLoggingPackedData (pValue, cbValue) :
將欄位資料新增至事件,而不新增任何欄位中繼資料。 必須透過中繼資料宏新增對應的中繼資料。
TraceLoggingPackedDataEx (pValue, cbValue, dataDescType) :
使用資料EVENT_DATA_DESCRIPTOR中的特定 Type
,將欄位資料新增至事件,而不新增任何欄位中繼資料。 必須透過中繼資料宏新增對應的中繼資料。
訓練
學習路徑
Implement finance and operations apps - Training
Plan and design your project methodology to successfully implement finance and operations apps with FastTrack services, data management and more.