Undantagssammanfattning

När du försöker generera meningsfulla diagnostiska meddelanden för undantag kan det vara en utmaning att upprätthålla inkluderingen av relevant information. Standardfelmeddelandet saknar ofta viktig information som medföljer undantaget, medan anrop av Exception.ToString metoden ger ett överskott av tillståndsinformation.

Den här artikeln förlitar sig på NuGet-paketet Microsoft.Extensions.Diagnostics.ExceptionSummarization .

Målet med undantagssammanfattning

Måtttaggar stöder vanligtvis ett begränsat antal distinkta värden och är därför inte lämpliga för att representera värden som är mycket varierande, till exempel resultatet av Exception.ToString(). En undantagssammanfattning representerar en version med låg kardinalitet av ett undantagsinformation som är lämplig för sådana fall.

Målet med undantagssammanfattning är två syften:

• Minska kardinaliteten som är associerad med undantagstillstånd så att undantag kan räknas i mått på ett tillförlitligt sätt. Detta är viktigt eftersom måttdimensioner har begränsad kardinalitet.
• För att eliminera sekretesskänslig information från undantagstillstånd så att viss meningsfull undantagsinformation kan läggas till i loggar.

API för undantagssammanfattning

Gränssnittet IExceptionSummarizer erbjuder metoder för att extrahera viktiga detaljer från identifierade undantagstyper, vilket ger en singular string som fungerar som grund för att skapa diagnostiska meddelanden av högsta kvalitet.

Metoden IExceptionSummarizer.Summarize går systematiskt igenom listan över registrerade sammanfattningar tills den identifierar en sammanfattning som kan hantera den specifika undantagstypen. Om ingen summarizer kan identifiera undantagstypen tillhandahålls i stället en meningsfull standardsammanfattning för undantag.

Resultatet av Summarize metoden returnerar en ExceptionSummary struct och innehåller följande egenskaper:

• ExceptionSummary.Description: Sammanfattningsbeskrivningen av undantaget.
• ExceptionSummary.AdditionalDetails: Den här egenskapen är avsedd för diagnostisk användning på låg nivå och innehåller ytterligare information om undantaget och har en relativt hög kardinalitet. Den här egenskapen kan innehålla sekretesskänslig information.
• ExceptionSummary.ExceptionType: Typen av undantag, såvida inte inre undantag finns, i vilket fall både yttre och inre typer återspeglas.

Exempel på användning av undantagssammanfattning

I följande exempel visas hur du använder IExceptionSummarizer gränssnittet för att hämta en sammanfattning av ett undantag.

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();

Föregående kod:

• Instansierar en ny ServiceCollection instans genom att länka ett anrop till AddExceptionSummarizer tilläggsmetoden.
  • Tilläggsmetoden AddExceptionSummarizer tar emot en delegering som används för att konfigurera ExceptionSummarizerBuilder-instansen.
  • builder Används för att lägga till HTTP-providern, som hanterar undantag av typen:
    • OperationCanceledException
    • TaskCanceledException
    • SocketException
    • WebException
• Skapar en ny ServiceProvider instans från instansen ServiceCollection .
• Hämtar en instans av IExceptionSummarizer gränssnittet från instansen ServiceProvider .
• Itererar över en samling undantag, anropar Summarize metoden för varje undantag och visar resultatet.