在 Azure Service Fabric、云服务和虚拟机中为 .NET 应用启用快照调试器

如果 ASP.NET 或 ASP.NET Core 应用程序 在 Azure 应用服务中运行,强烈建议通过 Application Insights 门户页启用 Snapshot Debugger。 但是,如果应用程序需要自定义的 Snapshot Debugger 配置或 .NET core 预览版,则除了通过 Application Insights 门户页启用的说明外,还应遵循此说明。

如果应用程序在 Azure Service Fabric、云服务、虚拟机或本地计算机中运行,则应使用以下说明。

为 ASP.NET 应用程序配置快照集合

  1. 如果尚未启用,请在 Web 应用中启用 Application Insights

  2. Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。

  3. 如果需要,自定义添加到 ApplicationInsights.config 的 Snapshot Debugger 配置。Snapshot Debugger 默认配置大部分为空,所有设置都是可选的。 以下示例显示与默认配置等效的配置:

    <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 Azure 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>
    
  4. 仅当向 Application Insights 报告了异常时,才收集快照。 在某些情况下(例如,.NET 平台为较早版本时),可能需要配置异常收集,才能在门户的查看附带快照的异常。

使用 ASP.NET Core LTS 或更高版本为应用程序配置快照收集

  1. 如果尚未启用,请在 ASP.NET Core Web 应用中启用 Application Insights

    注意

    请确保应用程序引用 2.1.1 版或更新版本的 Microsoft.ApplicationInsights.AspNetCore 包。

  2. Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。

  3. 修改应用程序的 Startup 类,添加并配置快照收集器的遥测处理器。

    1. 如果使用的是Microsoft.ApplicationInsights.SnapshotCollector NuGet 包版本 1.3.5 或更高版本,则将以下 using 语句添加到 Startup.cs

           using Microsoft.ApplicationInsights.SnapshotCollector;
      

      Startup.csStartup 类的 ConfigureServices 方法末尾添加以下内容。

           services.AddSnapshotCollector((configuration) => Configuration.Bind(nameof(SnapshotCollectorConfiguration), configuration));
      
    2. 如果使用的是Microsoft.ApplicationInsights.SnapshotCollector NuGet 包版本 1.3.4 或更低版本,则将以下 using 语句添加到 Startup.cs

      using Microsoft.ApplicationInsights.SnapshotCollector;
      using Microsoft.Extensions.Options;
      using Microsoft.ApplicationInsights.AspNetCore;
      using Microsoft.ApplicationInsights.Extensibility;
      

      将以下 SnapshotCollectorTelemetryProcessorFactory 类添加到 Startup 类。

      class Startup
      {
          private class SnapshotCollectorTelemetryProcessorFactory : ITelemetryProcessorFactory
          {
              private readonly IServiceProvider _serviceProvider;
      
              public SnapshotCollectorTelemetryProcessorFactory(IServiceProvider serviceProvider) =>
                  _serviceProvider = serviceProvider;
      
              public ITelemetryProcessor Create(ITelemetryProcessor next)
              {
                  var snapshotConfigurationOptions = _serviceProvider.GetService<IOptions<SnapshotCollectorConfiguration>>();
                  return new SnapshotCollectorTelemetryProcessor(next, configuration: snapshotConfigurationOptions.Value);
              }
          }
          ...
      

      SnapshotCollectorConfigurationSnapshotCollectorTelemetryProcessorFactory 服务添加到启动管道:

         // This method gets called by the runtime. Use this method to add services to the container.
         public void ConfigureServices(IServiceCollection services)
         {
             // Configure SnapshotCollector from application settings
             services.Configure<SnapshotCollectorConfiguration>(Configuration.GetSection(nameof(SnapshotCollectorConfiguration)));
      
             // Add SnapshotCollector telemetry processor.
             services.AddSingleton<ITelemetryProcessorFactory>(sp => new SnapshotCollectorTelemetryProcessorFactory(sp));
      
             // TODO: Add other services your application needs here.
         }
      }
      
  4. 如果需要,可通过在 appsetings.json 中添加 SnapshotCollectorConfiguration 节来自定义快照调试器配置。 快照调试器配置中的所有设置都是可选的。 以下示例显示与默认配置等效的配置:

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

为其他 .NET 应用程序配置快照集合

  1. 如果尚未在 Application Insights 上检测到你的应用程序,请先启用 Application Insights 并设置检测密钥

  2. Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。

  3. 仅当向 Application Insights 报告了异常时,才收集快照。 可能需要修改代码才能报告。 异常处理代码取决于应用程序的结构,示例如下:

    TelemetryClient _telemetryClient = new TelemetryClient();
    
    void ExampleRequest()
    {
        try
        {
            // TODO: Handle the request.
        }
        catch (Exception ex)
        {
            // Report the exception to Application Insights.
            _telemetryClient.TrackException(ex);
    
            // TODO: Rethrow the exception if desired.
        }
    }
    

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。 检测密钥引入功能将会继续工作,但我们将不再为该功能提供更新或支持。 转换为连接字符串,以利用新功能

后续步骤

  • 为应用程序生成可触发异常的流量。 然后等待 10 到 15 分钟,这样快照就会发送到 Application Insights 实例。
  • 请参见 Azure 门户中的快照
  • 排查 Snapshot Debugger 问题时如需帮助,请参阅 Snapshot Debugger 故障排除