Partilhar via

Habilitar o Depurador de Instantâneo para aplicativos .NET no Azure Service Fabric, Serviços de Nuvem e Máquinas Virtuais

  • Artigo

Se o seu aplicativo ASP.NET ou ASP.NET Core for executado no Serviço de Aplicativo do Azure e exigir uma configuração personalizada do Depurador de Instantâneo ou uma versão de visualização do .NET Core, comece com Habilitar o Depurador de Instantâneo para aplicativos .NET no Serviço de Aplicativo do Azure.

Se seu aplicativo for executado no Azure Service Fabric, Serviços de Nuvem do Azure, Máquinas Virtuais do Azure ou máquinas locais, você poderá ignorar a habilitação do Depurador de Instantâneo no Serviço de Aplicativo e seguir as orientações neste artigo.

Pré-requisitos

Configurar a coleta de instantâneos para aplicativos ASP.NET

Quando você adiciona o pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector ao seu aplicativo, o SnapshotCollectorTelemetryProcessor é adicionado automaticamente à TelemetryProcessors seção do ApplicationInsights.config.

Se você não vir SnapshotCollectorTelemetryProcessor no ApplicationInsights.config, ou se quiser personalizar a configuração do Depurador de Instantâneo, poderá editá-la manualmente.

Nota

Quaisquer configurações manuais podem ser substituídas ao atualizar para uma versão mais recente do pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector .

A configuração padrão do Snapshot Collector é semelhante ao exemplo a seguir:

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

Os instantâneos são coletados somente em exceções relatadas ao Application Insights. Em alguns casos (por exemplo, versões mais antigas da plataforma .NET), talvez seja necessário configurar a coleta de exceções para ver exceções com instantâneos no portal.

Configurar a coleta de instantâneos para aplicativos ASP.NET Core ou Worker Services

Pré-requisitos

Seu aplicativo já deve fazer referência a um dos seguintes pacotes NuGet do Application Insights:

Adicionar o pacote NuGet

Adicione o pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector ao seu aplicativo.

Atualizar a coleção de serviços

No código de inicialização do seu aplicativo, onde os serviços são configurados, adicione uma chamada ao AddSnapshotCollector método de extensão. Sugerimos adicionar esta linha imediatamente após a chamada para AddApplicationInsightsTelemetry. Por exemplo:

var builder = WebApplication.CreateBuilder(args);

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

Personalizar o coletor de instantâneo

Para a maioria dos cenários, as configurações padrão do Snapshot Collector são suficientes. No entanto, você pode personalizar as configurações adicionando o seguinte código antes da chamada para AddSnapshotCollector():

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

Em seguida, adicione uma SnapshotCollector seção à appsettings.json qual você pode substituir os padrões.

A configuração padrão appsettings.json do Snapshot Collector é semelhante ao exemplo a seguir:

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

Se você precisar personalizar o comportamento do Snapshot Collector manualmente, sem usar appsettings.json, use a sobrecarga de AddSnapshotCollector que leva um delegado. Por exemplo:

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

Configurar a coleta de instantâneos para outros aplicativos .NET

Os instantâneos são coletados somente em exceções relatadas ao Application Insights.

Para aplicativos ASP.NET e ASP.NET Core, o SDK do Application Insights relata automaticamente exceções não tratadas que escapam de um método de controlador ou manipulador de rota de ponto de extremidade.

Para outros aplicativos, talvez seja necessário modificar seu código para relatá-los. O código de tratamento de exceção depende da estrutura do seu aplicativo. Por exemplo:

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

O exemplo a seguir usa ILogger em vez de TelemetryClient. Este exemplo pressupõe que você esteja usando o Application Insights Logger Provider. Como mostra o exemplo, ao manipular uma exceção, certifique-se de passar a exceção como o primeiro parâmetro para 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.");
    }
  }
}

Por padrão, o Application Insights Logger (ApplicationInsightsLoggerProvider) encaminha exceções para o Depurador de Instantâneo via TelemetryClient.TrackException. Esse comportamento é controlado por meio da TrackExceptionsAsExceptionTelemetry propriedade na ApplicationInsightsLoggerOptions classe.

Se você definir TrackExceptionsAsExceptionTelemetry como ao false configurar o Application Insights Logger, o exemplo anterior não acionará o Depurador de Instantâneo. Nesse caso, modifique seu código para chamar TrackException manualmente.

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.

Próximos passos