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

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

• Aktivieren von Application Insights in Ihrer .NET-Ressource
• Binden Sie das NuGet-Paket Microsoft.ApplicationInsights.SnapshotCollector, Version 1.4.2 oder höher, in Ihre App ein.
• Verstehen Sie, dass es 10 bis 15 Minuten dauern kann, bis Momentaufnahmen an die Application Insights-Instanz gesendet werden, nachdem eine Ausnahme ausgelöst wurde.

Konfigurieren der Momentaufnahmesammlung für ASP.NET-Anwendungen

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

Wenn SnapshotCollectorTelemetryProcessor in ApplicationInsights.config nicht zu sehen ist oder wenn Sie die Konfiguration des Momentaufnahmedebuggers anpassen möchten, können Sie sie manuell bearbeiten.

Die Standardkonfiguration des Snapshot Collectors sieht ähnlich wie im folgenden Beispiel aus:

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

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

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 wird empfohlen, diese Zeile direkt hinter dem Aufruf von AddApplicationInsightsTelemetry hinzuzufügen. Zum Beispiel:

var builder = WebApplication.CreateBuilder(args);

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

Anpassen des Snapshot Collectors

In den meisten Szenarien reichen die Standardeinstellungen des Snapshot Collectors aus. Sie können die Einstellungen jedoch anpassen, 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 in appsettings.json hinzu, in dem Sie die Standardwerte überschreiben können.

Die appsettings.json-Standardkonfiguration des Snapshot Collectors sieht ähnlich wie im folgenden Beispiel aus:

{
  "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. Zum 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.");
    }
  }
}

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 de Application Insights-Protokollierung 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.

Nächste Schritte

• Zeigen Sie Momentaufnahmen im Azure-Portal an.
• Behandeln von Problemen mit dem Momentaufnahmedebugger.