例外狀況摘要

當您嘗試產生例外狀況的有意義診斷訊息時，維持相關資訊的完整性可能會帶來挑戰。 標準例外狀況訊息通常缺少例外狀況隨附的重要詳細數據，而叫 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
• 從 ServiceProvider 實例建置新的ServiceCollection實例。
• 從IExceptionSummarizer實例中獲取ServiceProvider介面的實例。
• 逐一查看例外狀況集合，在每個例外狀況上呼叫 Summarize 方法，並顯示結果。

備註

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