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

Článek
04/07/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 ve webové aplikaci Přehledy aplikace.
Zahrňte Microsoft.Application Přehledy. Balíček NuGet SnapshotCollector verze 1.4.2 nebo vyšší ve vaší aplikaci

Konfigurace kolekce snímků pro aplikace ASP.NET

Když přidáte Microsoft.Application Přehledy. Balíček NuGet SnapshotCollector do vaší aplikace, SnapshotCollectorTelemetryProcessor měl by se automaticky přidat do TelemetryProcessors části Application Přehledy.config.

Pokud v aplikaci nevidíte SnapshotCollectorTelemetryProcessor Přehledy.config nebo pokud 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 aplikace Microsoft.Application Přehledy. Balíček NuGet 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í pouze u výjimek hlášených v Přehledy aplikace. 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 už měla odkazovat na jeden z následujících balíčků NuGet Přehledy aplikací:

Přidejte balíček NuGet .

Přidejte Microsoft.Application Přehledy. Balíček NuGet SnapshotCollector do vaší aplikace

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 Přehledy aplikací. V případě aplikací ASP.NET a ASP.NET Core sada Application Přehledy 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 application Přehledy Logger. 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í aplikace Přehledy Logger (ApplicationInsightsLoggerProvider) předává výjimky do 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 aplikace Přehledy Logger, předchozí příklad neaktivuje Snapshot Debugger. V takovém případě upravte kód tak, aby volal TrackException ručně.