Activer le débogueur de capture instantanée pour des applications .NET dans Azure Service Fabric, Azure Cloud Services et Machines virtuelles Azure

Si votre application ASP.NET ou ASP.NET Core s’exécute dans Azure App Service et nécessite une configuration personnalisée du débogueur de capture instantanée ou une préversion de .NET Core, commencez par Activer le débogueur de capture instantanée pour des applications .NET dans Azure App Service.

Si votre application s’exécute dans Azure Service Fabric, Azure Cloud Services, Machines Virtuelles Azure ou sur des machines locales, vous pouvez ignorer l’activation du débogueur de capture instantanée sur App Services et suivre l’aide fournie dans ce guide.

Prérequis

• Activer Application Insights dans votre ressource .NET.
• Incluez dans votre application la version 1.4.2 ou ultérieure du package NuGet Microsoft.ApplicationInsights.SnapshotCollector.
• Comprendre que les captures instantanées peuvent prendre 10 à 15 minutes avant d’être envoyées à l’instance Application Insights une fois qu’une exception a été déclenchée.

Configurer la collecte de captures instantanées pour les applications ASP.NET

Lorsque vous ajoutez le package NuGet Microsoft.ApplicationInsights.SnapshotCollector à votre application, SnapshotCollectorTelemetryProcessor est ajouté automatiquement à la section TelemetryProcessors de ApplicationInsights.config.

Si vous ne voyez pas SnapshotCollectorTelemetryProcessor dans ApplicationInsights.config, ou si vous souhaitez personnaliser la configuration du Débogueur de capture instantanée, vous pouvez la modifier manuellement.

La configuration par défaut de Snapshot Collector ressemble à l’exemple suivant :

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

Des captures instantanées sont collectées uniquement sur des exceptions signalées à Application Insights. Dans certains cas (par exemple, des versions plus anciennes de la plateforme .NET), il se peut que vous deviez configurer la collecte des exceptions afin de voir celles-ci avec des captures instantanées dans le portail.

Configurer la collection d’instantanés pour les applications ASP.NET Core ou les services Worker

Prérequis

Votre application doit déjà référencer l’un des packages NuGet Application Insights suivants :

• Microsoft.ApplicationInsights.AspNetCore
• Microsoft.ApplicationInsights.WorkerService

Ajouter le package NuGet

Incluez dans votre application le package NuGet Microsoft.ApplicationInsights.SnapshotCollector.

Mettre à jour la collection de services

Dans le code de démarrage de votre application, où les services sont configurés, ajoutez un appel à la méthode d’extension AddSnapshotCollector. Nous suggérons d’ajouter cette ligne immédiatement après l’appel à AddApplicationInsightsTelemetry. Par exemple :

var builder = WebApplication.CreateBuilder(args);

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

Personnaliser Snapshot Collector

Pour la plupart des scénarios, les paramètres par défaut de Snapshot Collector sont suffisants. Toutefois, vous pouvez personnaliser les paramètres en ajoutant le code suivant avant l’appel à AddSnapshotCollector() :

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

Ajoutez ensuite une section SnapshotCollector à appsettings.json où vous pouvez remplacer les valeurs par défaut.

La configuration appsettings.json par défaut de Snapshot Collector ressemble à l’exemple suivant :

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

Si vous devez personnaliser manuellement le comportement de Snapshot Collector sans utiliser appsettings.json, servez-vous de la surcharge de AddSnapshotCollector qui prend un délégué. Par exemple :

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

Configurer la collecte de captures instantanées pour d’autres applications .NET

Des captures instantanées sont collectées uniquement sur des exceptions signalées à Application Insights.

Pour les applications ASP.NET et ASP.NET Core, le Kit de développement logiciel (SDK) Application Insights signale automatiquement les exceptions non prises en charge qui échappent à une méthode de contrôleur ou à un gestionnaire de routage de point de terminaison.

Pour d’autres applications, vous devrez peut-être modifier votre code pour les signaler. Le code de gestion des exceptions dépend de la structure de votre application. Par exemple :

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

L’exemple suivant utilise ILogger au lieu deTelemetryClient. Cet exemple suppose que vous utilisez le module fournisseur d’informations Application Insights. Comme l’illustre l’exemple, lorsque vous rencontrez une exception, veillez à passer l’exception comme premier paramètre à 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.");
    }
  }
}

Par défaut, l’enregistreur d’événements Application Insights (ApplicationInsightsLoggerProvider) transfère les exceptions au débogueur de capture instantanée via TelemetryClient.TrackException. Ce comportement est contrôlé via la propriété TrackExceptionsAsExceptionTelemetry sur la classe ApplicationInsightsLoggerOptions.

Si vous définissez TrackExceptionsAsExceptionTelemetry sur false lors de la configuration du journaliseur Application Insights, l’exemple précédent ne déclenche pas le Débogueur de capture instantanée. Dans ce cas, modifiez votre code pour appeler TrackException manuellement.

Étapes suivantes

• Affichez les captures instantanées dans le portail Azure.
• Résoudre les problèmes du Débogueur de capture instantanée.