撰寫檢測資訊清單

發行項
06/13/2023

應用程式和 DLL 會使用檢測資訊清單來識別其檢測提供者，以及提供者寫入的事件。資訊清單是 XML 檔案，其中包含識別提供者的專案。慣例是使用 .man 作為資訊清單的副檔名。資訊清單必須符合事件資訊清單 XSD。如需架構的詳細資訊，請參閱 EventManifest 架構。

檢測提供者是呼叫 EventWriteEx、 EventWriteString或 EventWriteTransfer 函式的任何應用程式或 DLL，以將事件寫入事件追蹤 (ETW) 追蹤會話或事件記錄通道。應用程式可以定義單一檢測提供者，涵蓋其寫入的所有事件，也可以定義應用程式的提供者及其每個 DLL 的提供者。應用程式在資訊清單中定義的提供者數目，只取決於應用程式想要組織其寫入的事件。

指定每個 DLL 提供者的優點是您可以接著啟用和停用個別提供者，因而產生事件。只有在 ETW 追蹤會話啟用提供者時，才適用這項優點。指定事件記錄檔通道的任何事件一律會寫入該通道。

資訊清單必須識別提供者及其寫入的事件，但通道、層級和關鍵字等其他中繼資料是選擇性的;您是否定義選擇性中繼資料，取決於將取用事件的人員。例如，如果系統管理員或支援人員使用從事件記錄檔通道讀取事件的 Windows 事件檢視器之類的工具來取用事件，則您必須定義寫入事件的通道。不過，如果提供者只會由 ETW 追蹤會話啟用，則您不需要定義通道。

雖然層級、工作、作業碼和關鍵字中繼資料是選擇性的，但您應該使用它們來以邏輯方式分組或貯體事件。將事件分組可協助取用者只取用感興趣的事件。例如，取用者可以查詢層級為「關鍵」且關鍵字為「寫入」的所有事件，或查詢特定工作所寫入的所有事件。

除了使用層級和關鍵字來取用特定類型的事件之外，ETW 追蹤會話還可以使用層級和關鍵字中繼資料來指示 ETW 限制寫入事件追蹤記錄的事件。例如，會話可以將事件限制為只有層級為「錯誤」或「重大」且關鍵字為「讀取」的事件。

提供者可以定義會話用來根據事件資料篩選事件的篩選。使用層級和關鍵字時，ETW 會判斷事件是否寫入記錄檔，但使用篩選準則，提供者會使用篩選資料準則來判斷是否將事件寫入該會話。只有在 ETW 追蹤會話啟用您的提供者時，才適用篩選準則。

下列各節示範如何定義資訊清單的元件：

雖然您可以手動撰寫檢測資訊清單，但您應該考慮使用包含在 Windows SDK \Bin 資料夾中的 ECManGen.exe 工具。 ECManGen.exe工具會使用 GUI，引導您從頭開始建立資訊清單，而不需要使用 XML 標記。瞭解本節和 EventManifest 架構一節中的資訊，在使用工具時將有所説明。

如果您使用 Visual Studio 做為 XML 編輯器，您可以將 EventManifest 架構新增至專案， (查看 XML 功能表) 利用 Intellisense、內嵌架構驗證和其他功能，讓撰寫資訊清單變得簡單且精確。

撰寫資訊清單之後，請使用訊息編譯器來驗證資訊清單，並產生您包含在提供者中的資源和標頭檔。如需詳細資訊，請參閱編譯檢測資訊清單。

下列範例顯示完整定義事件資訊清單的基本架構。

<instrumentationManifest
    xmlns="http://schemas.microsoft.com/win/2004/08/events" 
    xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    >

    <instrumentation>
        <events>
            <provider ...>
                <channels>
                    <importChannel .../>
                    <channel .../>
                </channels>
                <levels>
                    <level .../>
                </levels>
                <tasks>
                    <task .../>
                </tasks>
                <opcodes>
                    <opcode .../>
                </opcodes>
                <keywords>
                    <keyword .../>
                </keywords>
                <filters>
                    <filter .../>
                </filters>
                <maps>
                    <valueMap ...>
                        <map .../>
                    </valueMap>
                    <bitMap ...>
                        <map .../>
                    </bitMap>
                </maps>
                <templates>
                    <template ...>
                        <data .../>
                        <UserData>
                            <!-- valid XML fragment -->
                        </UserData>
                    </template>
                </templates>
                <events>
                    <event .../>
                </events>
            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources ...>
            <stringTable>
                <string .../>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>

共用方式為

撰寫檢測資訊清單

意見反應

其他資源