Udostępnij za pośrednictwem

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

  • Artykuł

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.

Wymagania wstępne

Konfigurowanie kolekcji migawek dla aplikacji ASP.NET

Po dodaniu pakietu NuGet Microsoft.ApplicationInsights.SnapshotCollector do aplikacji SnapshotCollectorTelemetryProcessor element zostanie automatycznie dodany do TelemetryProcessors sekcji .ApplicationInsights.config

Jeśli nie widzisz SnapshotCollectorTelemetryProcessor elementu w ApplicationInsights.configpliku lub jeśli chcesz dostosować konfigurację debugera migawek, możesz edytować ją ręcznie.

Uwaga

Wszelkie konfiguracje ręczne mogą zostać zastąpione podczas uaktualniania do nowszej wersji pakietu NuGet Microsoft.ApplicationInsights.SnapshotCollector .

Domyślna konfiguracja modułu zbierającego migawki wygląda podobnie do poniższego przykładu:

<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 w usłudze Application Insights. 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 usługi Application Insights:

Dodawanie pakietu NuGet

Dodaj pakiet NuGet Microsoft.ApplicationInsights.SnapshotCollector do aplikacji.

Aktualizowanie kolekcji usług

W kodzie uruchamiania aplikacji, w którym są skonfigurowane usługi, dodaj wywołanie metody AddSnapshotCollector rozszerzenia. Zalecamy 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();

Dostosowywanie modułu zbierającego migawki

W większości scenariuszy domyślne ustawienia modułu zbierającego migawki są wystarczające. Można jednak dostosować 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 której można zastąpić wartości domyślne.

Domyślna appsettings.json konfiguracja modułu zbierającego migawki wygląda podobnie do poniższego przykładu:

{
  "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 w usłudze Application Insights.

W przypadku aplikacji ASP.NET i ASP.NET Core zestaw SDK usługi Application Insights 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. Na 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 usługi Application Insights. 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.");
    }
  }
}

Domyślnie rejestrator usługi Application Insights (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 podczas konfigurowania rejestratora usługi Application Insights ustawiono wartość TrackExceptionsAsExceptionTelemetry na false wartość , powyższy przykład nie wyzwoli debugera migawek. W takim przypadku zmodyfikuj kod w celu ręcznego wywołania TrackException .

Uwaga

31 marca 2025 r. zostanie zakończone świadczenie pomocy technicznej dla pozyskiwania klucza instrumentacji. Pozyskiwanie klucza instrumentacji będzie nadal działać, ale nie udostępnimy już aktualizacji ani obsługi funkcji. Przejście do parametry połączenia w celu skorzystania z nowych funkcji.

Następne kroki