EventActivityIdControl 函式 (evntprov.h)

  • 發行項

建立、查詢及設定用於 ETW 事件的活動識別碼。

語法

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

參數

[in] ControlCode

控制程式代碼，指定要執行的作業。

  • EVENT_ACTIVITY_CTRL_GET_ID

    將 ActivityId 參數設定為目前線程的活動標識碼值。

  • EVENT_ACTIVITY_CTRL_SET_ID

    將目前線程的活動標識碼設定為 ActivityId 參數的值。

  • EVENT_ACTIVITY_CTRL_CREATE_ID

    將 ActivityId 參數設定為新產生的本機唯一活動識別碼的值。

  • EVENT_ACTIVITY_CTRL_GET_SET_ID

    交換 ActivityId 參數的值和目前線程的活動標識碼。 (儲存目前線程的活動標識碼值，然後將目前線程的活動標識碼設定為 ActivityId 參數的值，然後將 ActivityId 參數設定為已儲存的值。)

  • EVENT_ACTIVITY_CTRL_CREATE_SET_ID

    將 ActivityId 參數設定為目前線程的活動識別碼值，然後將目前線程的活動識別碼設定為新產生的本機唯一活動標識碼的值。

[in, out] ActivityId

緩衝區的指標，其中包含128位的活動標識碼。 視 ControlCode 參數的值而定，此緩衝區可能是讀取和/或寫入。

傳回值

如果成功 ， 則傳回ERROR_SUCCESS。

備註

使用其中一個 EventWrite API 撰寫的 ETW 事件將包含 128 位的「活動標識碼」欄位，而且可以選擇性地包含 128 位的「相關活動標識符」欄位。 追蹤處理工具可以使用這些欄位的值，將事件組織成稱為活動的群組。

  • 所有活動標識碼為零的事件 (亦即 ，假設GUID_NULL) 不屬於任何活動的一部分。
  • 所有具有特定非零活動標識碼的事件都會假設為相同活動的一部分。
  • 若要指出活動的開頭，提供者應該將Opcode設定為 WINEVENT_OPCODE_START 具有特定非零活動標識符的第一個事件， (開始 事件) 。 如果活動以邏輯方式巢狀在另一個活動內，提供者應該將 起始 事件的相關活動標識符字段設定為父活動的標識符。
  • 若要指出活動的結尾，提供者應該將Opcode 設定為WINEVENT_OPCODE_STOP 具有特定非零活動標識碼的最後一個事件， (停止 事件) 。

若要讓活動標識碼很有用，新產生的活動標識碼必須是本機唯一的，亦即，追蹤內不得產生相同的標識符兩次。

您可以使用 EventActivityIdControl 建立活動標識碼，此標識符會產生在本機唯一標識符，保證在系統重新啟動之前，在本機系統上的所有進程上都是唯一的。 您也可以使用 GUID (全域唯一識別碼) 作為活動識別碼。 您可以使用 UuidCreate 之類的 API 來建立 GUID。

使用者模式線程具有線程本機 128 位活動標識符值， (線程的活動標識碼) 。 線程活動標識碼會初始化為 0 (，也就是建立線程時 ，GUID_NULL) 。 線程活動標識碼可以使用 EventActivityIdControl 來讀取或更新。 線程活動標識碼將做為 EventWrite 所寫入之所有事件的活動識別碼，以及 EventWriteTransfer 或 EventWriteEx 所寫入的所有事件的活動標識符，其中 ActivityId 參數為 NULL。

重要

改變線程活動標識碼的函式應該小心還原原始活動標識碼，再結束。 否則，函式對線程活動標識符的變更會干擾呼叫函式的元件活動。

使用明確指定的活動標識碼

如果您的活動不限於單一線程，或您想要避免其他元件覆寫線程活動標識符的可能性，您可能想要透過 EventWriteTransfer 或 EventWriteEx 的 ActivityId 字段明確指定事件活動，而不是使用自動線程活動標識符。

如果使用 指令清單 和 訊息編譯程式 來寫入事件，則由 MC.exe -um 使用線程的活動標識碼所產生的宏，而由 MC.exe -km 產生的宏則支援活動標識元參數。 原本， -um 宏只能在使用者模式中運作，而 -km 宏只能在內核模式中運作，因此使用者模式程式代碼只能使用目前線程的活動標識符。 不過，從 MC.exe 10.0.17741 版開始，產生的 MC.exe -km 宏可以同時用於使用者模式和核心模式，因此您可以使用 MC.exe -km 來產生接受活動標識符參數的宏。 (MC 產生的程式代碼不支援設定事件的相關活動標識碼。)

如果使用 TraceLoggingProvider.h 寫入事件， TraceLoggingWrite 宏會使用線程的活動標識符，而 TraceLoggingWriteActivity 則接受活動標識符和相關活動標識符的參數。 或者，您可以針對 TraceLogging 活動使用 TraceLoggingActivity.h 中的 C++ 類別。

規格需求

需求 值
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 evntprov.h
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

EventWriteTransfer