Freigeben über

Zusammenfassung der Ausnahme

  • Artikel

Wenn Sie versuchen, aussagekräftige Diagnosemeldungen für Ausnahmen zu generieren, kann die Aufrechterhaltung der Einbeziehung relevanter Informationen eine Herausforderung darstellen. In der Standardausnahmemeldung fehlen häufig kritische Details, die die Ausnahme begleiten, während das Aufrufen der Exception.ToString-Methode zu einem Übermaß an Zustandsinformationen führt.

Dieser Artikel basiert auf dem NuGet-Paket Microsoft.Extensions.Diagnostics.ExceptionSummarization.

Ziel der Zusammenfassung der Ausnahme

Metriktags unterstützen in der Regel eine begrenzte Anzahl unterschiedlicher Werte und sind daher nicht geeignet, um Werte darzustellen, die sehr variabel sind, z. B. das Ergebnis von Exception.ToString(). Eine Ausnahmezusammenfassung stellt eine Version mit niedriger Kardinalität der Informationen einer Ausnahme dar, die für solche Fälle geeignet ist.

Das Ziel der Ausnahmezusammenfassung dient einem doppelten Zweck:

  • Um die Kardinalität zu verringern, die dem Ausnahmezustand zugeordnet ist, sodass Ausnahmen in Metriken zuverlässig gezählt werden können. Dies ist wichtig, da die Metrikdimensionen eingeschränkte Kardinalität aufweisen.
  • Um datenschutzrelevante Informationen aus dem Ausnahmezustand zu entfernen, sodass einige aussagekräftige Ausnahmeinformationen zu Protokollen hinzugefügt werden können.

API der Zusammenfassung der Ausnahme

Die IExceptionSummarizer-Schnittstelle bietet Methoden zum Extrahieren von wichtigen Details aus anerkannten Ausnahmetypen, wodurch eine einzelne string eingerichtet wird, die als Grundlage für die Herstellung hochwertiger Diagnosemeldungen dient.

Die IExceptionSummarizer.Summarize-Methode durchläuft systematisch die Liste der registrierten Zusammenfassungen, bis ein Zusammenfassungselement identifiziert wird, das den spezifischen Ausnahmetyp verarbeiten kann. Wenn kein Zusammenfassungselement in der Lage ist, den Ausnahmetyp zu erkennen, wird stattdessen eine aussagekräftige Standardausnahmezusammenfassung bereitgestellt.

Das Ergebnis der Summarize-Methode gibt eine ExceptionSummary-Struktur zurück und enthält die folgenden Eigenschaften:

  • ExceptionSummary.Description: Eine zusammenfassende Beschreibung der Ausnahme
  • ExceptionSummary.AdditionalDetails: Für die Diagnose auf niedriger Ebene vorgesehen, enthält diese Eigenschaft zusätzliche Details zur Ausnahme und weist eine relativ hohe Kardinalität auf. Diese Eigenschaft kann vertrauliche Informationen enthalten.
  • ExceptionSummary.ExceptionType: Der Typ der Ausnahme, es sei denn, interne Ausnahmen sind vorhanden; in diesem Fall werden sowohl äußere als auch innere Typen wiedergegeben.

Beispiel für eine Zusammenfassung der Ausnahme

Im folgenden Beispiel wird veranschaulicht, wie Sie die IExceptionSummarizer-Schnittstelle verwenden, um eine Zusammenfassung einer Ausnahme abzurufen.

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

Der vorangehende Code:

  • Instanziiert eine neue ServiceCollection-Instanz, wobei Aufrufe der AddExceptionSummarizer-Erweiterungsmethode verkettet werden.
  • Erstellt eine neue ServiceProvider-Instanz aus der ServiceCollection-Instanz
  • Ruft eine Instanz der IExceptionSummarizer-Schnittstelle aus der ServiceProvider-Instanz ab
  • Durchläuft eine Sammlung von Ausnahmen, ruft die Summarize-Methode für jede Ausnahme auf und zeigt das Ergebnis an

Hinweis

Der Hauptfokus bei der Gestaltung aller Implementierungen der Ausnahmezusammenfassung ist die Bereitstellung einer einfachen Diagnose, anstatt den Schutz personenbezogener Informationen (PII) zu priorisieren. Die ExceptionSummary.Description-Eigenschaft enthält keine vertraulichen Informationen, aber die ExceptionSummary.AdditionalDetails-Eigenschaft enthält abhängig von der Implementierung möglicherweise vertrauliche Informationen.