Aktivieren des Momentaufnahmedebuggers für .NET-Anwendungen in Azure Service Fabric, Cloud Services und Virtual Machines

  • Artikel

Wenn Ihre ASP.NET- oder ASP.NET Core-Anwendung in Azure App Service ausgeführt wird und eine benutzerdefinierte Konfiguration des Momentaufnahmedebuggers oder eine Vorschauversion von .NET Core benötigt, beginnen Sie mit dem Aktivieren des Momentaufnahmedebuggers für .NET-Anwendungen in Azure App Service.

Wenn Ihre Anwendung in Azure Service Fabric, Microsoft Azure Virtual Machines, Microsoft Azure Virtual Machines oder lokalen Computern ausgeführt wird, können Sie die Aktivierung des Momentaufnahmedebuggers für App Services überspringen und direkt mit diesem Leitfaden beginnen.

Voraussetzungen

Konfigurieren der Momentaufnahmesammlung für ASP.NET-Anwendungen

Wenn Sie in Ihre Anwendung das NuGet-Paket Microsoft.ApplicationInsights.SnapshotCollector einbinden, sollte der SnapshotCollectorTelemetryProcessor automatisch dem TelemetryProcessors-Abschnitt von ApplicationInsights.config hinzugefügt werden.

Wenn in „ApplicationInsights.config“ SnapshotCollectorTelemetryProcessor nicht zu sehen ist, oder wenn Sie die Konfiguration des Momentaufnahmedebuggers anpassen möchten, können Sie sie manuell bearbeiten. Diese Änderungen werden jedoch möglicherweise überschrieben, wenn Sie später ein Upgrade auf eine neuere Version des NuGet-Pakets Microsoft.ApplicationInsights.SnapshotCollector durchführen.

Das folgende Beispiel zeigt eine Konfiguration, die der Standardkonfiguration entspricht:

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

Momentaufnahmen werden nur zu Ausnahmen erfasst, die Application Insights gemeldet wurden. In einigen Fällen (z.B. bei älteren Versionen der .NET-Plattform) müssen Sie möglicherweise die Ausnahmesammlung konfigurieren, um Ausnahmen mit Momentaufnahmen im Portal zu sehen.

Konfigurieren des Snapshot Collectors für ASP.NET Core-Anwendungen oder Workerdienste

Voraussetzungen

Ihre Anwendung sollte bereits auf eins der folgenden Application Insights NuGet-Pakete verweisen:

Hinzufügen des NuGet-Pakets

Fügen Sie das NuGet-Paket Microsoft.ApplicationInsights.SnapshotCollector zu Ihrer App hinzu.

Aktualisieren der Dienstesammlung

Fügen Sie im Startcode Ihrer Anwendung, wo Dienste konfiguriert werden, einen Aufruf der AddSnapshotCollector-Erweiterungsmethode hinzu. Es ist ratsam, diese Zeile direkt hinter dem Aufruf von AddApplicationInsightsTelemetry hinzuzufügen. Beispiele:

var builder = WebApplication.CreateBuilder(args);

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

Konfigurieren des Snapshot Collectors

Für die meisten Situationen reichen die Standardeinstellungen aus. Falls nicht, passen Sie die Einstellungen an, indem Sie den folgenden Code vor dem Aufruf von AddSnapshotCollector() hinzufügen.

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

Fügen Sie als Nächstes einen SnapshotCollector-Abschnitt zu appsettings.json hinzu, in dem Sie die Standardwerte überschreiben können. Das folgende Beispiel zeigt eine Konfiguration, die der Standardkonfiguration entspricht:

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

Wenn Sie das Verhalten des Snapshot Collectors manuell anpassen müssen, ohne appsettings.json zu verwenden, verwenden Sie die Überladung von AddSnapshotCollector, die einen Delegaten akzeptiert. Beispiele:

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

Konfigurieren der Momentaufnahmesammlung für andere .NET-Anwendungen

Momentaufnahmen werden nur zu Ausnahmen erfasst, die Application Insights gemeldet wurden. Für ASP.NET- und ASP.NET Core-Anwendungen meldet das Application Insights SDK automatisch nicht behandelte Ausnahmen, die einer Controllermethode oder einem Endpunkt-Routenhandler entgehen. Für andere Anwendungen müssen Sie möglicherweise Ihren Code ändern, um sie zu melden. Der Code zur Behandlung von Ausnahmen hängt von der Struktur Ihrer Anwendung ab. Ein Beispiel:

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

Das folgende Beispiel verwendet ILogger anstelle von TelemetryClient. In diesem Beispiel wird davon ausgegangen, dass Sie den Application Insights Logger Provider verwenden. Wie das Beispiel zeigt, müssen Sie beim Behandeln einer Ausnahme unbedingt die Ausnahme als ersten Parameter übergeben an 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.");
    }
  }
}

Hinweis

Standardmäßig leitet der Application Insights Logger (ApplicationInsightsLoggerProvider) Ausnahmen vom Momentaufnahmedebugger über TelemetryClient.TrackException. Dieses Verhalten wird über die TrackExceptionsAsExceptionTelemetry-Eigenschaft der ApplicationInsightsLoggerOptions-Klasse gesteuert. Wenn Sie beim Konfigurieren des Application Insights Loggers TrackExceptionsAsExceptionTelemetry auf false festlegen, löst das vorangehende Beispiel den Momentaufnahmedebugger nicht aus. Ändern Sie in diesem Fall den Code so, dass TrackException manuell aufgerufen wird.

Hinweis

Am 31. März 2025 wird der Support für die auf Instrumentierungsschlüsseln basierende Erfassung eingestellt. Die Erfassung von Instrumentierungsschlüsseln funktioniert zwar weiterhin, wir stellen jedoch keine Updates und keinen Support mehr für das Feature bereit. Wechseln Sie zu Verbindungszeichenfolgen, damit Sie neue Funktionen nutzen können.

Nächste Schritte

  • Generieren Sie Datenverkehr für Ihre Anwendung, der eine Ausnahme auslösen kann. Warten Sie dann 10 bis 15 Minuten, bis die Momentaufnahmen an die Application Insights-Instanz gesendet werden.
  • Weitere Informationen finden Sie unter Momentaufnahmen im Azure-Portal.
  • Behandeln von Problemen mit dem Momentaufnahmedebugger.