開始使用 EventSource

發行項
01/29/2025

本文適用於： ✔️ .NET Core 3.1 和更新版本 ✔️ .NET Framework 4.5 和更新版本

本逐步解說示範如何使用 System.Diagnostics.Tracing.EventSource記錄新事件、收集追蹤檔案中的事件、檢視追蹤，以及瞭解基本 EventSource 概念。

注意

與 EventSource 整合的許多技術都會使用「追蹤」和「追蹤記錄」一詞，而不是「日誌記錄」。意義在這裡相同。

記錄事件

EventSource 的目標是允許 .NET 開發人員撰寫類似此的程式代碼來記錄事件：

DemoEventSource.Log.AppStarted("Hello World!", 12);

這一行程式代碼具有記錄物件（DemoEventSource.Log）、表示要記錄事件的方法（AppStarted），以及選擇性的一些強型別事件參數（HelloWorld! 和 12）。沒有任何詳細資訊層級、事件 ID、訊息範本或在呼叫點不需要的其他項目。定義衍生自 System.Diagnostics.Tracing.EventSource的新類別，即可撰寫所有有關事件的其他資訊。

以下是完整的基本範例：

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
    }
}

DemoEventSource 類別會針對您想要記錄的每個事件類型宣告方法。在此情況下，AppStarted（）方法會定義名為『AppStarted』的單一事件。每次程式代碼叫用 AppStarted 方法時，如果已啟用事件，則會在追蹤中記錄另一個 AppStarted 事件。這是可使用每個事件擷取的一些數據：

事件名稱 - 識別所記錄事件類型的名稱。在此案例中，事件名稱會與方法名稱『AppStarted』相同。
事件標識碼 - 識別所記錄事件種類的數字識別碼。這與名稱類似，但可協助快速自動處理記錄。 AppStarted 事件在 EventAttribute中指定標識碼為 1。
來源名稱 - 包含事件的 EventSource 名稱。這會做為事件的命名空間。事件名稱和標識碼只需要在其來源的範圍內是唯一的。在此，來源名為「Demo」，在類別定義的 EventSourceAttribute 中指定。來源名稱通常也稱為提供者名稱。
自變數 - 所有方法自變數值都會串行化。
其他資訊 - 事件也可以包含時間戳、線程標識碼、處理器標識碼、活動標識碼、堆疊追蹤，以及事件元數據，例如訊息範本、詳細資訊層級和關鍵詞。

如需建立事件的詳細資訊和最佳做法，請參閱檢測程式代碼以建立事件。

收集及檢視追蹤檔案

在程序代碼中不需要配置，以確定應啟用哪些事件、日誌數據應傳送到哪裡，或資料應以何種格式儲存。如果您現在執行應用程式，它預設不會產生任何追蹤檔案。 EventSource 會使用 Publish-subscribe 模式，這需要訂閱者指出應啟用的事件，以及控制訂閱事件的所有串行化。 EventSource 具有從 Windows 事件追蹤（ETW）和 EventPipe（僅限 .NET Core）訂閱的集成。您也可以使用 System.Diagnostics.Tracing.EventListener API 來建立自訂訂閱者。

此示範顯示 .NET Core 應用程式的 EventPipe 範例。若要深入瞭解選項，請參閱收集及檢視事件追蹤。 EventPipe 是 .NET Core 執行時間內建的開放式跨平臺追蹤技術，可提供 .NET 開發人員追蹤收集工具和可攜式精簡追蹤格式（*.nettrace 檔案）。 dotnet-trace 是收集 EventPipe 追蹤的命令行工具。

下載並安裝 dotnet-trace 。
建置上述控制台應用程式。此示範假設應用程式名為 EventSourceDemo.exe，且位於目前目錄中。在命令列上執行：

>dotnet-trace collect --providers Demo -- EventSourceDemo.exe

這應該會顯示如下的輸出：

Provider Name                           Keywords            Level               Enabled By
Demo                                    0xFFFFFFFFFFFFFFFF  Verbose(5)          --providers

Launching: EventSourceDemo.exe
Process        : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
Output File    : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220303_001619.nettrace

[00:00:00:00]   Recording trace 0.00     (B)
Press <Enter> or <Ctrl+C> to exit...

Trace completed.

此指令在 'Demo' EventSource 中啟用所有事件後執行 EventSourceDemo.exe，並輸出追蹤檔案 EventSourceDemo.exe_20220303_001619.nettrace。在 Visual Studio 中開啟檔案會顯示已記錄的事件。

在清單檢視中，您可以看到第一個事件是 Demo/AppStarted 事件。文本欄中具有已儲存的參數，時間戳欄會顯示事件在記錄開始 27 毫秒後發生，而在右側你可以看到呼叫堆疊。其他事件會在 dotnet-trace 所收集的每個追蹤中自動啟用，但這些事件若造成干擾，可以在 UI 中忽略和篩選掉。這些額外的事件會擷取一些有關流程和JIT編譯代碼的信息，這可讓 Visual Studio 重新建構事件堆疊追蹤記錄。

共用方式為

開始使用 EventSource

記錄事件

收集及檢視追蹤檔案

深入瞭解 EventSource

其他資源