Sdílet prostřednictvím

Souhrn výjimek

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 postrádá kritické detaily, které výjimku provázejí, zatímco vyvolání Exception.ToString metody vede k přílišnému množství informací 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 neidentifikuje sumarizátor, 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:

  • ExceptionSummary.Description: Souhrnný popis výjimky.
  • ExceptionSummary.AdditionalDetails: Tato vlastnost je určena pro nízkoúrovňové diagnostické použití, obsahuje další podrobnosti o výjimce a má relativně vysokou kardinalitu. Tato vlastnost může obsahovat citlivé informace o ochraně osobních údajů.
  • ExceptionSummary.ExceptionType: Typ výjimky, pokud nejsou přítomny vnitřní výjimky, v takovém případě se promítnou vnější i vnitřní typy.

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ří novou instanci ServiceCollection, která volá AddExceptionSummarizer metodu 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.

  • Last updated on