在 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.cs 中 Startup 类的 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);
              }
          }
          ...
      

      将 SnapshotCollectorConfiguration 和 SnapshotCollectorTelemetryProcessorFactory 服务添加到启动管道：

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

后续步骤

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