Sdílet prostřednictvím

Povolení nástroje Snapshot Debugger pro aplikace .NET v Azure Service Fabric, Cloud Services a Virtual Machines

  • Článek

Pokud vaše aplikace ASP.NET nebo ASP.NET Core běží ve službě Aplikace Azure a vyžaduje přizpůsobenou konfiguraci ladicího programu snímků nebo verzi Preview .NET Core, začněte s povolením nástroje Snapshot Debugger pro aplikace .NET ve službě Aplikace Azure Service.

Pokud vaše aplikace běží v Azure Service Fabric, Azure Cloud Services, Azure Virtual Machines nebo na místních počítačích, můžete přeskočit povolení snapshot Debuggeru ve službě App Service a postupovat podle pokynů v tomto článku.

Požadavky

Konfigurace kolekce snímků pro aplikace ASP.NET

Když do aplikace přidáte balíček NuGet Microsoft.ApplicationInsights.SnapshotCollector , přidá se SnapshotCollectorTelemetryProcessor automaticky do TelemetryProcessors části ApplicationInsights.configsouboru .

Pokud se nezobrazuje SnapshotCollectorTelemetryProcessor nebo ApplicationInsights.configpokud chcete přizpůsobit konfiguraci snapshot Debuggeru, můžete ji upravit ručně.

Poznámka:

Všechny ruční konfigurace se můžou při upgradu na novější verzi balíčku NuGet Microsoft.ApplicationInsights.SnapshotCollector přepsat.

Výchozí konfigurace kolekce snímků vypadá podobně jako v následujícím příkladu:

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

Snímky se shromažďují jenom na výjimkách hlášených do Application Insights. V některých případech (například starší verze platformy .NET) možná budete muset nakonfigurovat kolekci výjimek, aby se na portálu zobrazily výjimky se snímky.

Konfigurace kolekce snímků pro aplikace ASP.NET Core nebo pracovní služby

Požadavky

Vaše aplikace by již měla odkazovat na jeden z následujících balíčků NuGet Application Insights:

Přidejte balíček NuGet .

Přidejte do aplikace balíček NuGet Microsoft.ApplicationInsights.SnapshotCollector .

Aktualizace kolekce služeb

Ve spouštěcím kódu aplikace, kde jsou služby nakonfigurované, přidejte volání AddSnapshotCollector metody rozšíření. Doporučujeme přidat tento řádek ihned po volání AddApplicationInsightsTelemetry. Příklad:

var builder = WebApplication.CreateBuilder(args);

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

Přizpůsobení kolektoru snímků

Pro většinu scénářů stačí výchozí nastavení kolekce snímků. Nastavení ale můžete přizpůsobit přidáním následujícího kódu před voláním AddSnapshotCollector():

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

Dále přidejte SnapshotCollector oddíl, do appsettings.json kterého můžete přepsat výchozí hodnoty.

Výchozí appsettings.json konfigurace kolekce snímků vypadá podobně jako v následujícím příkladu:

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

Pokud potřebujete chování kolektoru snímků přizpůsobit ručně bez použití appsettings.json, použijte přetížení AddSnapshotCollector , které přebírá delegáta. Příklad:

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

Konfigurace kolekce snímků pro jiné aplikace .NET

Snímky se shromažďují jenom u výjimek, které jsou hlášeny do Application Insights.

V případě aplikací ASP.NET a ASP.NET Core sada Application Insights SDK automaticky hlásí neošetřené výjimky, které uniknou metodě kontroleru nebo obslužné rutině trasy koncového bodu.

V případě jiných aplikací možná budete muset upravit kód tak, aby je nahlásil. Kód zpracování výjimek závisí na struktuře vaší aplikace. Příklad:

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

Následující příklad používá ILogger místo TelemetryClient. Tento příklad předpokládá, že používáte zprostředkovatele protokolovacího nástroje Application Insights. Jak ukazuje příklad, při zpracování výjimky nezapomeňte předat výjimku jako první parametr 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.");
    }
  }
}

Ve výchozím nastavení protokolovací nástroj Application Insights (ApplicationInsightsLoggerProvider) předává výjimky do programu Snapshot Debugger prostřednictvím TelemetryClient.TrackException. Toto chování je řízeno prostřednictvím TrackExceptionsAsExceptionTelemetry vlastnosti třídy ApplicationInsightsLoggerOptions .

Pokud nastavíte TrackExceptionsAsExceptionTelemetry false při konfiguraci nástroje Application Insights Logger, předchozí příklad neaktivuje ladicí program Snapshot. V takovém případě upravte kód tak, aby volal TrackException ručně.

Poznámka:

Podpora příjmu dat založeného na instrumentačním klíči skončí 31. března 2025. Příjem klíčů instrumentace bude dál fungovat, ale už nebudeme poskytovat aktualizace ani podporu pro tuto funkci. Přechod na připojovací řetězec, abyste mohli využívat nové funkce.

Další kroky