Sdílet prostřednictvím

Souhrn výjimek

  • Článek

Když se snažíte generovat smysluplné diagnostické zprávy pro výjimky, může zachování zahrnutí relevantních informací představovat výzvu. Standardní zpráva o výjimce často chybí kritické podrobnosti, které k výjimce doprovázejí, zatímco vyvolání Exception.ToString metody přináší nadbytečné informace o stavu.

Tento článek se spoléhá na balíček NuGet Microsoft.Extensions.Diagnostics.ExceptionSummarization .

Cíl souhrnu výjimek

Značky metrik obvykle podporují omezený počet jedinečných hodnot a proto nejsou vhodné k reprezentaci hodnot, které jsou vysoce proměnné, například výsledek Exception.ToString(). Souhrn výjimek představuje verzi informací o výjimce s nízkou kardinalitou, která je vhodná pro takové případy.

Cílem sumarizace výjimek je dvojí:

  • Chcete-li snížit kardinalitu spojenou se stavem výjimky, aby bylo možné spolehlivě počítat výjimky v metrikách. Záleží na tom, protože dimenze metrik mají omezenou kardinalitu.
  • Chcete-li odstranit informace citlivé na ochranu osobních údajů ze stavu výjimky, aby bylo možné do protokolů přidat některé smysluplné informace o výjimce.

Rozhraní API pro sumarizaci výjimek

Rozhraní IExceptionSummarizer nabízí metody pro extrakci zásadních podrobností z rozpoznaných typů výjimek, a proto poskytuje jednotné číslo string , které slouží jako základ pro vytváření diagnostických zpráv nejvyšší kvality.

Metoda IExceptionSummarizer.Summarize systematicky prochází seznam registrovaných sumarizátorů, dokud neidentifikaci sumarizátoru, který dokáže zpracovat konkrétní typ výjimky. V případě, že žádný sumarizátor nedokáže rozpoznat typ výjimky, je místo toho k dispozici smysluplný výchozí souhrn výjimek.

Výsledek Summarize metody vrátí ExceptionSummary strukturu a obsahuje následující vlastnosti:

Příklad využití souhrnu výjimek

Následující příklad ukazuje, jak použít IExceptionSummarizer rozhraní k načtení souhrnu výjimky.

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

Předchozí kód:

  • Vytvoří instanci nové ServiceCollection instance a zřetězí volání AddExceptionSummarizer metody rozšíření.
  • Vytvoří novou ServiceProvider instanci z ServiceCollection instance.
  • Získá instanci IExceptionSummarizer rozhraní z ServiceProvider instance.
  • Iteruje nad kolekcí výjimek, volá metodu Summarize pro každou výjimku a zobrazí výsledek.

Poznámka:

Primárním cílem při návrhu všech implementací souhrnů výjimek je poskytnout diagnostické pohodlí místo stanovení priority ochrany identifikovatelných osobních údajů (PII). Neobsahuje ExceptionSummary.Description citlivé informace, ale ExceptionSummary.AdditionalDetails může obsahovat citlivé informace v závislosti na implementaci.