例外狀況摘要

當您嘗試為例外狀況產生有意義的診斷訊息時，維護包含相關的資訊可能會帶來挑戰。 標準的例外狀況訊息通常缺少例外狀況隨附的重要詳細資料，而叫用 Exception.ToString 方法則會產生過多的狀態資訊。

本文依賴 Microsoft.Extensions.Diagnostics.ExceptionSummarization NuGet 套件。

例外狀況摘要的目標

計量標記通常支援有限的相異值數目，因此它們不適合表示變化極大的值，例如 Exception.ToString() 的結果。 例外狀況摘要代表例外狀況資訊的低基數版本，適用於這類情況。

例外狀況摘要的目標有兩個：

• 減少與例外狀況狀態相關聯的基數，以便可以在計量中可靠地計算例外狀況的數目。 這點很重要，因為計量維度的基數有限。
• 從例外狀況狀態中排除隱私敏感性資訊，以便可以將一些有意義的例外狀況資訊新增至記錄中。

例外狀況摘要 API

IExceptionSummarizer 介面可提供從識別的例外狀況類型中擷取重要​詳細資料的方法，從而提供一個單一的 string，以作為製作高品質診斷訊息的基礎。

IExceptionSummarizer.Summarize 方法可有系統地遍歷已註冊的摘要器名冊，直到它找到能夠處理特定例外狀況類型的摘要器為止。 如果沒有任何摘要器能夠辨識例外狀況類型，則會改為提供有意義的預設例外狀況摘要。

Summarize 方法的結果會傳回 ExceptionSummary 結構，並包含下列屬性：

• ExceptionSummary.Description：例外狀況的摘要描述。
• ExceptionSummary.AdditionalDetails：此屬性適用於低階診斷用途，它包含有關例外狀況的其他詳細資料，並且具有相對較高的基數。 此屬性可能包含隱私敏感性資訊。
• ExceptionSummary.ExceptionType：例外狀況的類型；除非存在內部外狀況 (在這種情況下，外部類型和內部類型都會被反映)，否則會出現此屬性。

範例例外狀況摘要的用法

下列範例示範如何使用 IExceptionSummarizer 介面來擷取例外狀況的摘要。

using System.Net;
using System.Net.Sockets;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Diagnostics.ExceptionSummarization;

// Add exception summarization services.
var services = new ServiceCollection()
    .AddExceptionSummarizer(static builder => builder.AddHttpProvider());

var provider = services.BuildServiceProvider();

// Get the exception summarizer.
IExceptionSummarizer summarizer = provider.GetRequiredService<IExceptionSummarizer>();

// Define exceptions to summarize.
Exception[] exceptions =
[
    new OperationCanceledException("Operation cancelled..."),
    new TaskCanceledException("Task cancelled..."),
    new SocketException(10_024, "Too many sockets open..."),
    new WebException("Keep alive failure...",
        WebExceptionStatus.KeepAliveFailure)
];

foreach (var exception in exceptions)
{
    // Summarize the exception.
    ExceptionSummary summary = summarizer.Summarize(exception);

    Console.WriteLine(summary);
}

Console.ReadLine();

上述 程式碼：

• 具現化一個新的 ServiceCollection 執行個體，鏈結對 AddExceptionSummarizer 擴充方法的呼叫。
  • AddExceptionSummarizer 擴充方法接受用於設定 ExceptionSummarizerBuilder 執行個體的委派。
  • builder 用於新增 HTTP 提供者，以處理下列類型的例外狀況：
    • OperationCanceledException
    • TaskCanceledException
    • SocketException
    • WebException
• 從 ServiceCollection 執行個體中建置一個新的 ServiceProvider 執行個體。
• 從 ServiceProvider 執行個體中取得 IExceptionSummarizer 介面的執行個體。
• 逐一查看例外狀況的集合，以對每個例外狀況呼叫 Summarize 方法並顯示結果。

注意

所有例外狀況摘要實作設計的主要重點是為了提供診斷的便利性，而不是優先考慮個人識別資訊 (PII) 的保護。 ExceptionSummary.Description 不包含敏感性資訊，但 ExceptionSummary.AdditionalDetails 可能會根據實作情況而包含敏感性資訊。