Włączanie debugera migawek dla aplikacji platformy .NET w usłudze Azure Service Fabric, usługach w chmurze i maszynach wirtualnych

Artykuł
04/07/2024

Jeśli aplikacja ASP.NET lub ASP.NET Core działa w usłudze aplikacja systemu Azure i wymaga dostosowanej konfiguracji debugera migawek lub wersji zapoznawczej platformy .NET Core, zacznij od opcji Włącz debuger migawek dla aplikacji platformy .NET w usłudze aplikacja systemu Azure Service.

Jeśli aplikacja działa w usłudze Azure Service Fabric, Azure Cloud Services, Azure Virtual Machines lub na maszynach lokalnych, możesz pominąć włączanie debugera migawek w usłudze App Service i postępować zgodnie ze wskazówkami w tym artykule.

Zanim rozpoczniesz

Włącz Szczegółowe informacje aplikacji internetowej.
Uwzględnij aplikację Microsoft.Application Szczegółowe informacje. Pakiet NuGet SnapshotCollector w wersji 1.4.2 lub nowszej w aplikacji.

Konfigurowanie kolekcji migawek dla aplikacji ASP.NET

Po dodaniu aplikacji Microsoft.Application Szczegółowe informacje. Pakiet NuGet SnapshotCollector do aplikacji SnapshotCollectorTelemetryProcessor powinien zostać dodany automatycznie do TelemetryProcessors sekcji Application Szczegółowe informacje.config.

Jeśli nie widzisz SnapshotCollectorTelemetryProcessor pliku Application Szczegółowe informacje.config lub chcesz dostosować konfigurację debugera migawek, możesz ją edytować ręcznie. Te zmiany mogą jednak zostać zastąpione w przypadku późniejszego uaktualnienia do nowszej wersji aplikacji Microsoft.Application Szczegółowe informacje. Pakiet NuGet snapshotCollector.

W poniższym przykładzie przedstawiono konfigurację równoważną konfiguracji domyślnej:

<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>

Migawki są zbierane tylko w przypadku wyjątków zgłoszonych do Szczegółowe informacje aplikacji. W niektórych przypadkach (na przykład starsze wersje platformy .NET) może być konieczne skonfigurowanie kolekcji wyjątków w celu wyświetlenia wyjątków z migawkami w portalu.

Konfigurowanie kolekcji migawek dla aplikacji ASP.NET Core lub usług procesów roboczych

Wymagania wstępne

Aplikacja powinna już odwoływać się do jednego z następujących pakietów NuGet application Szczegółowe informacje:

Dodawanie pakietu NuGet

Dodaj aplikację Microsoft.Application Szczegółowe informacje. Pakiet NuGet SnapshotCollector do aplikacji.

Aktualizowanie kolekcji usług

W kodzie uruchamiania aplikacji, w którym są skonfigurowane usługi, dodaj wywołanie metody AddSnapshotCollector rozszerzenia. Dobrym pomysłem jest dodanie tego wiersza bezpośrednio po wywołaniu metody .AddApplicationInsightsTelemetry Na przykład:

var builder = WebApplication.CreateBuilder(args);

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

Konfigurowanie modułu zbierającego migawki

W większości sytuacji ustawienia domyślne są wystarczające. Jeśli nie, dostosuj ustawienia, dodając następujący kod przed wywołaniem metody AddSnapshotCollector()

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

Następnie dodaj sekcję SnapshotCollector do appsettings.json , w której można zastąpić wartości domyślne. W poniższym przykładzie przedstawiono konfigurację równoważną konfiguracji domyślnej:

{
  "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
  }
}

Jeśli musisz ręcznie dostosować zachowanie modułu zbierającego migawki bez używania appsettings.json, użyj przeciążenia AddSnapshotCollector , które pobiera delegata. Na przykład:

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

Konfigurowanie kolekcji migawek dla innych aplikacji platformy .NET

Migawki są zbierane tylko w przypadku wyjątków zgłaszanych do Szczegółowe informacje aplikacji. W przypadku aplikacji ASP.NET i ASP.NET Core zestaw SDK usługi Application Szczegółowe informacje automatycznie zgłasza nieobsługiwane wyjątki, które unikną metody kontrolera lub procedury obsługi tras punktu końcowego. W przypadku innych aplikacji może być konieczne zmodyfikowanie kodu w celu ich raportowania. Kod obsługi wyjątków zależy od struktury aplikacji. Oto przykład:

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.
    }
  }
}

W poniższym przykładzie użyto wartości ILogger zamiast TelemetryClient. W tym przykładzie założono, że używasz dostawcy rejestratora aplikacji Szczegółowe informacje. Jak pokazano w przykładzie, podczas obsługi wyjątku pamiętaj o przekazaniu wyjątku jako pierwszego parametru 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.");
    }
  }
}

Uwaga

Domyślnie rejestrator aplikacji Szczegółowe informacje (ApplicationInsightsLoggerProvider) przekazuje wyjątki do debugera migawek za pomocą polecenia TelemetryClient.TrackException. To zachowanie jest kontrolowane za pośrednictwem TrackExceptionsAsExceptionTelemetry właściwości w ApplicationInsightsLoggerOptions klasie. Jeśli ustawisz wartość TrackExceptionsAsExceptionTelemetry na false podczas konfigurowania rejestratora aplikacji Szczegółowe informacje, poprzedni przykład nie wyzwoli debugera migawek. W takim przypadku zmodyfikuj kod w celu ręcznego wywołania TrackException .