我可以自定義 DoTraceMessage 嗎？

發行項
02/06/2024

是，您可以撰寫自己的 DoTraceMessage 宏版本。 DoTraceMessage 會產生追蹤訊息。

TraceDrv 範例驅動程式提供本主題所述的方法範例。 TraceDrv 可在 GitHub 上的 Windows 驅動程式範例存放庫中取得。

DoTraceMessage：預設版本

根據預設，DoTraceMessage 宏的格式如下：

DoTraceMessage(Flag,"Message",MessageVariables...);

在此預設版本中， Flag 代表追蹤旗標，這是產生訊息的條件。 MessageVariables 包含驅動程式定義且出現在追蹤訊息中的變數逗號分隔清單。 MessageVariables 變數是使用 printf 元素格式化。 WPP 預處理器會從 DoTraceMessage 宏建立編譯程式指示詞。此宏會將訊息定義資訊和格式化資訊新增至為追蹤提供者產生的 PDB 檔案，例如核心模式驅動程式或使用者模式應用程式。

DoTraceMessage 宏會以邏輯方式展開為下列專案：

PRE macro // If defined
If (WPP_CHECK_INIT && Flag is enabled) {
 ....Call WmiTraceMessage;
}
POST macro // If defined

請考慮下列程式碼範例。

DoTraceMessage(ERROR, "IOCTL = %d", ControlCode);

啟用 ERROR 旗標時，此呼叫會產生追蹤訊息。訊息為 “IOCTL=%d”， MessageVariables 是 ControlCode 的值。

如果已定義 PRE-logging 和 POST 記錄宏，它們也會展開。 Microsoft Windows 2000 和更新版本的操作系統支援 PRE 宏和 POST 宏。若要使用宏，您必須使用WDK來建置驅動程式。如果您使用舊版的 Windows 驅動程式開發工具包來建置驅動程式， (DDK) ，則無法使用 PRE 和 POST 功能，而且宏將不會在追蹤語句中執行。使用舊版 Windows DDK 建置驅動程式可能不會造成組建中斷，但程式代碼無法如預期般運作。

DoTraceMessage：一般格式

以下是有效追蹤訊息函式的一般格式：

FunctionName(Conditions...,"Message",MessageVariables...);

訊息之前出現的參數會解譯為條件。訊息之後出現的參數會解譯為訊息變數。

條件是以逗號分隔的值清單。只有在所有條件都成立時，才會產生追蹤訊息。您可以指定程式代碼中支援的任何條件。

範例：MyTrace

以下是追蹤函式的範例。本範例會新增追蹤層級的條件，以及產生追蹤訊息之提供者的子元件。

MyDoTrace(Level, Flag, Subcomponent,"Message",MessageVariables...);

例如：

MyDoTrace(TRACE_LEVEL_ERROR, VERBOSE, Network,"IOCTL = %d", ControlCode);

追蹤層級是在 Evntrace.h 中定義的標準層級，這是 WDK 的 Include 子目錄中的公用頭檔。

#define TRACE_LEVEL_NONE        0   // Tracing is not on
#define TRACE_LEVEL_FATAL       1   // Abnormal exit or termination
#define TRACE_LEVEL_ERROR       2   // Severe errors that need logging
#define TRACE_LEVEL_WARNING     3   // Warnings such as allocation failure
#define TRACE_LEVEL_INFORMATION 4   // Includes non-error cases(for example, Entry-Exit)
#define TRACE_LEVEL_VERBOSE     5   // Detailed traces from intermediate steps
#define TRACE_LEVEL_RESERVED6   6
#define TRACE_LEVEL_RESERVED7   7
#define TRACE_LEVEL_RESERVED8   8
#define TRACE_LEVEL_RESERVED9   9

如何建立自定義追蹤函式

若要建立自定義追蹤函式，請遵循下列步驟：

撰寫支援 DoTraceMessage 宏的宏替代版本。
將 -func 參數新增至叫用 WPP 預處理器的 RUN_WPP 語句。

撰寫自定義宏

若要建立自定義追蹤函式，以變更追蹤訊息的條件， (出現在訊息) 之前的參數，您必須撰寫支持追蹤函式的替代宏版本， WPP_LEVEL_ENABLED 和 WPP_LEVEL_LOGGER。

WPP_LEVEL_ENABLED (Flags) 判斷是否使用指定的旗標值啟用記錄。它會傳回 TRUE 或 FALSE。
WPP_LEVEL_LOGGER (旗標) 會尋找啟用提供者的追蹤會話，並傳回追蹤會話的句柄。

例如，如果您想要包含追蹤層級，除了旗標之外，還有條件，請定義包含追蹤層級的新WPP_LEVEL_ENABLED宏。您可以在默認宏上根據新宏的定義，如下列程式代碼範例所示。

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

一般而言，WPP_LEVEL_LOGGER宏不會受到影響。在這些情況下，您可以將新的宏定義為預設宏。例如：

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

不過，在某些情況下，您必須變更LOGGER宏。例如，您可能想要撰寫只取決於追蹤層級而非旗標的追蹤函式。

在下列程式代碼範例中，宏中的旗標值會取代為虛擬值。宣告控件 GUID 定義時，不會定義旗標。

#define WPP_CONTROL_GUIDS \
   WPP_DEFINE_CONTROL_GUID(CtlGuid,(a044090f,3d9d,48cf,b7ee,9fb114702dc1),  \
        WPP_DEFINE_BIT(DUMMY))

#define WPP_LEVEL_LOGGER(lvl) (WPP_CONTROL(WPP_BIT_ ## DUMMY).Logger)

將函式新增至 WPP

若要將自定義追蹤函式新增至 WPP，請使用函式宣告將 -func 參數新增至 RUN_WPP 語句，如下列程式代碼範例所示。

RUN_WPP=$(SOURCES) -km -func:DoTraceLevelMessage(LEVEL,FLAGS,MSG,...)

注意您不得在使用者模式應用程式或動態連結庫的 RUN_WPP 指示詞中指定 -km 參數， (DLL) 。

如需RUN_WPP選用參數的完整清單，請參閱 WPP 預處理器。

共用方式為