在 Azure Service Fabric、Azure 雲端服務和 Azure 虛擬機中啟用 .NET 應用程式的快照偵錯工具

發行項
10/15/2024

如果您的 ASP.NET 或 ASP.NET Core 應用程式在 App Service 中執行，而且需要自訂的快照偵錯工具設定或 .NET Core 的預覽版本，請從 [在 Azure App Service 中啟用適用於 .NET 應用程式的快照偵錯工具] 開始。

如果您的應用程式是在 Azure Service Fabric、Azure 雲端服務、Azure 虛擬機器或內部部署機器中執行，您可以略過在 App Services 上啟用快照偵錯工具，並遵循本文中的指導。

必要條件

啟用 .NET 資源中的 Application Insights。
將 Microsoft.ApplicationInsights.SnapshotCollector NuGet 套件版本 1.4.2 或更高版本納入您的應用程式。
理解在觸發例外狀況之後，可能需要 10 到 15 分鐘才會將快照傳送至 Application Insights 執行個體。

設定 ASP.NET 應用程式的快照集集合

當您將 Microsoft.ApplicationInsights.SnapshotCollector NuGet 套件新增至您的應用程式時，會自動將 SnapshotCollectorTelemetryProcessor 新增至 ApplicationInsights.config 的 [TelemetryProcessors] 區段。

如果您在 ApplicationInsights.config 中看不到 SnapshotCollectorTelemetryProcessor，或如果您想要自訂快照偵錯工具設定，可以手動編輯它。

注意

任何手動設定在升級至較新版本的 Microsoft.ApplicationInsights.SnapshotCollector NuGet 套件時，可能會遭到覆寫。

Snapshot Collector 的預設設定看起來類似如下範例：

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

快照集只會收集向 Application Insights 回報的例外狀況。在某些情況下 (例如，舊版的 .NET 平台)，您可能需要設定例外狀況集合，才能在入口網站中查看快照集的例外狀況。

設定 ASP.NET Core 應用程式或 Worker Service 的快照集集合

必要條件

您的應用程式應該已經參考下列其中一個 Application Insights NuGet 套件:

新增 NuGet 套件

將 Microsoft.ApplicationInsights.SnapshotCollector NuGet 套件新增至您的應用程式。

更新服務集合

在設定服務的應用程式啟動程式碼中，新增對 AddSnapshotCollector 擴充方法的呼叫。建議在呼叫 AddApplicationInsightsTelemetry 之後立即新增這一行。例如：

var builder = WebApplication.CreateBuilder(args);

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

自訂 Snapshot Collector

在大部分情況下，Snapshot Collector 的預設設定就已足夠。不然，請在呼叫 AddSnapshotCollector() 之前新增下列程式碼來自訂設定：

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

接下來，將 [SnapshotCollector] 區段新增至 appsettings.json，您可以在其中覆寫預設值。

Snapshot Collector 的預設 appsettings.json 設定看起來類似如下範例：

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

如果您需要手動自訂 Snapshot Collector 的行為，而不使用 appsettings.json，請使用接受委派的 AddSnapshotCollector 多載。例如：

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

設定其他 .NET 應用程式的快照集集合

快照集只會收集向 Application Insights 回報的例外狀況。

針對 ASP.NET 和 ASP.NET Core 應用程式，Application Insights SDK 會自動報告逸出控制器方法或端點路由處理程式的未處理的例外狀況。

對於其他應用程式，您可能需要修改程式碼以報告它們。例外狀況處理程式碼取決於應用程式的結構。例如：

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

下列範例使用 ILogger 而非 TelemetryClient。此範例假設您使用 Application Insights 記錄器提供者。如範例所示，當處理例外狀況時，請務必將例外狀況作為第一參數傳遞至 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.");
    }
  }
}

根據預設，Application Insights 記錄器 (ApplicationInsightsLoggerProvider) 會透過 TelemetryClient.TrackException 將例外狀況轉送至快照偵錯工具。此行為是透過 ApplicationInsightsLoggerOptions 類別上的 TrackExceptionsAsExceptionTelemetry 屬性來控制。

如果您在設定 Application Insights 記錄器時將 TrackExceptionsAsExceptionTelemetry 設定為 false，則上述範例並不會觸發快照偵錯工具。在此情況下，請修改程式碼以手動呼叫 TrackException。

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。轉換至連接字串以利用新功能。

下一步

在 Azure 入口網站檢視快照集。
針對快照偵錯工具問題進行疑難排解。

共用方式為

在 Azure Service Fabric、Azure 雲端服務和 Azure 虛擬機中啟用 .NET 應用程式的快照偵錯工具

必要條件

設定 ASP.NET 應用程式的快照集集合

設定 ASP.NET Core 應用程式或 Worker Service 的快照集集合

必要條件

新增 NuGet 套件

更新服務集合

自訂 Snapshot Collector

設定其他 .NET 應用程式的快照集集合

下一步

意見反應

其他資源