Samenvatting van uitzonderingen

Wanneer u zinvolle diagnostische berichten voor uitzonderingen probeert te genereren, kan het bijhouden van relevante informatie een uitdaging vormen. Het standaard-uitzonderingsbericht ontbreekt vaak aan kritieke details die bij de uitzondering horen, terwijl het aanroepen van de Exception.ToString methode een overschot aan statusinformatie oplevert.

Dit artikel is afhankelijk van het NuGet-pakket Microsoft.Extensions.Diagnostics.ExceptionSummarization .

Het doel van uitzonderingssamenvatting

Metrische tags ondersteunen doorgaans een beperkt aantal afzonderlijke waarden en daarom zijn ze niet geschikt om waarden weer te geven die zeer variabel zijn, zoals het resultaat van Exception.ToString(). Een uitzonderingsoverzicht vertegenwoordigt een versie met een lage kardinaliteit van de informatie van een uitzondering die geschikt is voor dergelijke gevallen.

Het doel van uitzonderingssamenvatting is tweeledig:

• Om de kardinaliteit te verminderen die is gekoppeld aan de uitzonderingsstatus, zodat uitzonderingen betrouwbaar kunnen worden geteld in metrische gegevens. Dit is belangrijk omdat metrische dimensies beperkte kardinaliteit hebben.
• Om privacygevoelige informatie uit de uitzonderingsstatus te elimineren, zodat bepaalde zinvolle uitzonderingsinformatie kan worden toegevoegd aan logboeken.

Samenvattings-API voor uitzonderingen

De IExceptionSummarizer interface biedt methoden voor het extraheren van cruciale details van herkende uitzonderingstypen, waardoor een enkelvoud string wordt ingericht die fungeert als de basis voor het maken van diagnostische berichten van topkwaliteit.

De IExceptionSummarizer.Summarize methode doorkruist systematisch het rooster van geregistreerde summarizers totdat een summarizer wordt geïdentificeerd die het specifieke uitzonderingstype kan verwerken. In het geval dat er geen overzicht kan worden herkend van het uitzonderingstype, wordt in plaats daarvan een zinvolle standaard uitzonderingssamenvatting opgegeven.

Het resultaat van de Summarize methode retourneert een ExceptionSummary struct en bevat de volgende eigenschappen:

• ExceptionSummary.Description: De samenvattingsbeschrijving van de uitzondering.
• ExceptionSummary.AdditionalDetails: Bedoeld voor diagnostisch gebruik op laag niveau, deze eigenschap bevat aanvullende informatie over de uitzondering en heeft een relatief hoge kardinaliteit. Deze eigenschap kan privacygevoelige informatie bevatten.
• ExceptionSummary.ExceptionType: Het type uitzondering, tenzij er binnenste uitzonderingen aanwezig zijn, waarbij zowel buiten- als binnenste typen worden weerspiegeld.

Voorbeeld van samenvattingsgebruik van uitzonderingen

In het volgende voorbeeld ziet u hoe u de IExceptionSummarizer interface gebruikt om een samenvatting van een uitzondering op te halen.

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

Met de voorgaande code wordt:

• Instantieert een nieuw ServiceCollection exemplaar, waarbij een aanroep naar de AddExceptionSummarizer extensiemethode wordt gekoppeld.
  • De AddExceptionSummarizer extensiemethode accepteert een gemachtigde die wordt gebruikt om het ExceptionSummarizerBuilder exemplaar te configureren.
  • Deze builder wordt gebruikt om de HTTP-provider toe te voegen, waarmee uitzonderingen van het type worden verwerkt:
    • OperationCanceledException
    • TaskCanceledException
    • SocketException
    • WebException
• Hiermee wordt een nieuw ServiceProvider exemplaar van het ServiceCollection exemplaar gebouwd.
• Hiermee haalt u een exemplaar van de IExceptionSummarizer interface van het ServiceProvider exemplaar op.
• Doorloopt een verzameling uitzonderingen, waarbij de Summarize methode voor elke uitzondering wordt aangeroepen en het resultaat wordt weergegeven.

Notitie

De primaire focus in het ontwerp van alle implementaties van uitzonderingssamenvattingen is om diagnostisch gemak te bieden, in plaats van de bescherming van persoonlijke identificeerbare informatie (PII) te prioriteren. De ExceptionSummary.Description gegevens bevatten geen gevoelige informatie, maar de ExceptionSummary.AdditionalDetails informatie bevat mogelijk gevoelige informatie, afhankelijk van de implementatie.