Povolení nástroje Snapshot Debugger pro aplikace .NET v Azure Service Fabric, Cloud Services a Virtual Machines

Článek
06/13/2024

Pokud vaše aplikace ASP.NET nebo ASP.NET Core běží ve službě Aplikace Azure a vyžaduje přizpůsobenou konfiguraci ladicího programu snímků nebo verzi Preview .NET Core, začněte s povolením nástroje Snapshot Debugger pro aplikace .NET ve službě Aplikace Azure Service.

Pokud vaše aplikace běží v Azure Service Fabric, Azure Cloud Services, Azure Virtual Machines nebo na místních počítačích, můžete přeskočit povolení snapshot Debuggeru ve službě App Service a postupovat podle pokynů v tomto článku.

Než začnete

Povolte Application Insights ve webové aplikaci.
Do aplikace zahrňte balíček NuGet Microsoft.ApplicationInsights.SnapshotCollector verze 1.4.2 nebo vyšší.

Konfigurace kolekce snímků pro aplikace ASP.NET

Když do aplikace přidáte balíček NuGet Microsoft.ApplicationInsights.SnapshotCollector , SnapshotCollectorTelemetryProcessor měl by se automaticky přidat do TelemetryProcessors části ApplicationInsights.config.

Pokud se v souboru ApplicationInsights.config nezobrazuje SnapshotCollectorTelemetryProcessor nebo chcete přizpůsobit konfiguraci snapshot Debuggeru, můžete ji upravit ručně. Tyto úpravy se však můžou přepsat, pokud později upgradujete na novější verzi balíčku NuGet Microsoft.ApplicationInsights.SnapshotCollector .

Následující příklad ukazuje konfiguraci, která odpovídá výchozí konfiguraci:

<TelemetryProcessors>
  <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
    <!-- The default is true, but you can disable Snapshot Debugging by setting it to false -->
    <IsEnabled>true</IsEnabled>
    <!-- Snapshot Debugging is usually disabled in developer mode, but you can enable it by setting this to true. -->
    <!-- DeveloperMode is a property on the active TelemetryChannel. -->
    <IsEnabledInDeveloperMode>false</IsEnabledInDeveloperMode>
    <!-- How many times we need to see an exception before we ask for snapshots. -->
    <ThresholdForSnapshotting>1</ThresholdForSnapshotting>
    <!-- The maximum number of examples we create for a single problem. -->
    <MaximumSnapshotsRequired>3</MaximumSnapshotsRequired>
    <!-- The maximum number of problems that we can be tracking at any time. -->
    <MaximumCollectionPlanSize>50</MaximumCollectionPlanSize>
    <!-- How often we reconnect to the stamp. The default value is 15 minutes.-->
    <ReconnectInterval>00:15:00</ReconnectInterval>
    <!-- How often to reset problem counters. -->
    <ProblemCounterResetInterval>1.00:00:00</ProblemCounterResetInterval>
    <!-- The maximum number of snapshots allowed in ten minutes.The default value is 1. -->
    <SnapshotsPerTenMinutesLimit>3</SnapshotsPerTenMinutesLimit>
    <!-- The maximum number of snapshots allowed per day. -->
    <SnapshotsPerDayLimit>30</SnapshotsPerDayLimit>
    <!-- Whether or not to collect snapshot in low IO priority thread. The default value is true. -->
    <SnapshotInLowPriorityThread>true</SnapshotInLowPriorityThread>
    <!-- Agree to send anonymous data to Microsoft to make this product better. -->
    <ProvideAnonymousTelemetry>true</ProvideAnonymousTelemetry>
    <!-- The limit on the number of failed requests to request snapshots before the telemetry processor is disabled. -->
    <FailedRequestLimit>3</FailedRequestLimit>
  </Add>
</TelemetryProcessors>

Snímky se shromažďují jenom na výjimkách hlášených do Application Insights. V některých případech (například starší verze platformy .NET) možná budete muset nakonfigurovat kolekci výjimek, aby se na portálu zobrazily výjimky se snímky.

Konfigurace kolekce snímků pro aplikace ASP.NET Core nebo pracovní služby

Požadavky

Vaše aplikace by již měla odkazovat na jeden z následujících balíčků NuGet Application Insights:

Přidejte balíček NuGet .

Přidejte do aplikace balíček NuGet Microsoft.ApplicationInsights.SnapshotCollector .

Aktualizace kolekce služeb

Ve spouštěcím kódu aplikace, kde jsou služby nakonfigurované, přidejte volání AddSnapshotCollector metody rozšíření. Tento řádek je vhodné přidat hned po volání AddApplicationInsightsTelemetry. Příklad:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddSnapshotCollector();

Konfigurace kolektoru snímků

Ve většině situací stačí výchozí nastavení. Pokud ne, přizpůsobte nastavení přidáním následujícího kódu před voláním AddSnapshotCollector()

using Microsoft.ApplicationInsights.SnapshotCollector;
...
builder.Services.Configure<SnapshotCollectorConfiguration>(builder.Configuration.GetSection("SnapshotCollector"));

Dále přidejte SnapshotCollector oddíl, který appsettings.json , kde můžete přepsat výchozí hodnoty. Následující příklad ukazuje konfiguraci, která odpovídá výchozí konfiguraci:

{
  "SnapshotCollector": {
    "IsEnabledInDeveloperMode": false,
    "ThresholdForSnapshotting": 1,
    "MaximumSnapshotsRequired": 3,
    "MaximumCollectionPlanSize": 50,
    "ReconnectInterval": "00:15:00",
    "ProblemCounterResetInterval":"1.00:00:00",
    "SnapshotsPerTenMinutesLimit": 1,
    "SnapshotsPerDayLimit": 30,
    "SnapshotInLowPriorityThread": true,
    "ProvideAnonymousTelemetry": true,
    "FailedRequestLimit": 3
  }
}

Pokud potřebujete chování kolektoru snímků přizpůsobit ručně bez použití appsettings.json, použijte přetížení AddSnapshotCollector , které přebírá delegáta. Příklad:

builder.Services.AddSnapshotCollector(config => config.IsEnabledInDeveloperMode = true);

Konfigurace kolekce snímků pro jiné aplikace .NET

Snímky se shromažďují jenom u výjimek, které jsou hlášeny do Application Insights. V případě aplikací ASP.NET a ASP.NET Core sada Application Insights SDK automaticky hlásí neošetřené výjimky, které uniknou metodě kontroleru nebo obslužné rutině trasy koncového bodu. V případě jiných aplikací možná budete muset upravit kód tak, aby je nahlásil. Kód zpracování výjimek závisí na struktuře vaší aplikace. Tady je příklad:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

internal class ExampleService
{
  private readonly TelemetryClient _telemetryClient;

  public ExampleService(TelemetryClient telemetryClient)
  {
    // Obtain the TelemetryClient via dependency injection.
    _telemetryClient = telemetryClient;
  }

  public void HandleExampleRequest()
  {
    using IOperationHolder<RequestTelemetry> operation = 
        _telemetryClient.StartOperation<RequestTelemetry>("Example");
    try
    {
      // TODO: Handle the request.
      operation.Telemetry.Success = true;
    }
    catch (Exception ex)
    {
      // Report the exception to Application Insights.
      operation.Telemetry.Success = false;
      _telemetryClient.TrackException(ex);
      // TODO: Rethrow the exception if desired.
    }
  }
}

Následující příklad používá ILogger místo TelemetryClient. Tento příklad předpokládá, že používáte zprostředkovatele protokolovacího nástroje Application Insights. Jak ukazuje příklad, při zpracování výjimky nezapomeňte předat výjimku jako první parametr do LogError.

using Microsoft.Extensions.Logging;

internal class LoggerExample
{
  private readonly ILogger _logger;

  public LoggerExample(ILogger<LoggerExample> logger)
  {
    _logger = logger;
  }

  public void HandleExampleRequest()
  {
    using IDisposable scope = _logger.BeginScope("Example");
    try
    {
      // TODO: Handle the request
    }
    catch (Exception ex)
    {
      // Use the LogError overload with an Exception as the first parameter.
      _logger.LogError(ex, "An error occurred.");
    }
  }
}

Poznámka:

Ve výchozím nastavení protokolovací nástroj Application Insights (ApplicationInsightsLoggerProvider) předává výjimky do programu Snapshot Debugger prostřednictvím TelemetryClient.TrackException. Toto chování je řízeno prostřednictvím TrackExceptionsAsExceptionTelemetry vlastnosti třídy ApplicationInsightsLoggerOptions . Pokud jste nastavili TrackExceptionsAsExceptionTelemetryfalse při konfiguraci protokolovacího nástroje Application Insights, předchozí příklad neaktivuje ladicí program Snapshot Debugger. V takovém případě upravte kód tak, aby volal TrackException ručně.