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.

Avant de commencer

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

Lorsque vous ajoutez le package NuGet Microsoft.ApplicationInsights.SnapshotCollector à votre application, SnapshotCollectorTelemetryProcessor doit être 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. Toutefois, ces modifications peuvent être remplacées si vous effectuez ultérieurement une mise à niveau vers une version plus récente du package NuGet Microsoft.ApplicationInsights.SnapshotCollector.

L’exemple suivant montre une configuration équivalente à la configuration par défaut :

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

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. Il est conseillé 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();

Configurer Snapshot Collector

Dans la plupart des cas, les paramètres par défaut sont suffisants. Si ce n’est pas le cas, personnalisez 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. L’exemple suivant montre une configuration équivalente à la configuration par défaut :

{
  "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. Voici un exemple :

TelemetryClient _telemetryClient = new TelemetryClient();
void ExampleRequest()
{
    try
    {
        // TODO: Handle the request.
    }
    catch (Exception ex)
    {
        // Report the exception to Application Insights.
        _telemetryClient.TrackException(ex);
        // TODO: Rethrow the exception if desired.
    }
}

Notes

Le support de l’ingestion de clé d’instrumentation prendra fin le 31 mars 2025. L’ingestion de clé d’instrumentation continuera de fonctionner, mais nous ne fournirons plus de mises à jour ni de support pour la fonctionnalité. Passez aux chaînes de connexion pour tirer parti des nouvelles fonctionnalités.

Étapes suivantes