您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

在 Azure Service Fabric、云服务和虚拟机中为 .NET 应用启用快照调试器Enable Snapshot Debugger for .NET apps in Azure Service Fabric, Cloud Service, and Virtual Machines

如果 ASP.NET 或 ASP.NET Core 应用程序 在 Azure 应用服务中运行,强烈建议通过 Application Insights 门户页启用 Snapshot DebuggerIf your ASP.NET or ASP.NET core application runs in Azure App Service, it's highly recommended to enable Snapshot Debugger through the Application Insights portal page. 但是,如果应用程序需要自定义的 Snapshot Debugger 配置或 .NET core 预览版,则 除了通过 Application Insights 门户页启用的说明外,还应遵循此说明。However, if your application requires a customized Snapshot Debugger configuration, or a preview version of .NET core, then this instruction should be followed in addition to the instructions for enabling through the Application Insights portal page.

如果应用程序在 Azure Service Fabric、云服务、虚拟机或本地计算机中运行,则应使用以下说明。If your application runs in Azure Service Fabric, Cloud Service, Virtual Machines, or on-premises machines, the following instructions should be used.

为 ASP.NET 应用程序配置快照集合Configure snapshot collection for ASP.NET applications

  1. 如果尚未启用,请在 Web 应用中启用 Application InsightsEnable Application Insights in your web app, if you haven't done it yet.

  2. Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。Include the Microsoft.ApplicationInsights.SnapshotCollector NuGet package in your app.

  3. 如果需要,可自定义添加到 ApplicationInsights.config 的快照调试器配置。默认快照调试器配置大多为空,并且所有设置都是可选的。If needed, customized the Snapshot Debugger configuration added to ApplicationInsights.config. The default Snapshot Debugger configuration is mostly empty and all settings are optional. 以下示例显示与默认配置等效的配置:Here is an example showing a configuration equivalent to the default configuration:

    <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>
    
  4. 仅当向 Application Insights 报告了异常时,才收集快照。Snapshots are collected only on exceptions that are reported to Application Insights. 在某些情况下(例如,.NET 平台为较早版本时),可能需要配置异常收集,才能在门户的查看附带快照的异常。In some cases (for example, older versions of the .NET platform), you might need to configure exception collection to see exceptions with snapshots in the portal.

使用 ASP.NET Core 2.0 或更高版本为应用程序配置快照收集Configure snapshot collection for applications using ASP.NET Core 2.0 or above

  1. 如果尚未启用,请在 ASP.NET Core Web 应用中启用 Application InsightsEnable Application Insights in your ASP.NET Core web app, if you haven't done it yet.

    备注

    请确保应用程序引用 2.1.1 版或更新版本的 Microsoft.ApplicationInsights.AspNetCore 包。Be sure that your application references version 2.1.1, or newer, of the Microsoft.ApplicationInsights.AspNetCore package.

  2. Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。Include the Microsoft.ApplicationInsights.SnapshotCollector NuGet package in your app.

  3. 修改应用程序的 Startup 类,添加并配置快照收集器的遥测处理器。Modify your application's Startup class to add and configure the Snapshot Collector's telemetry processor.

    1. 如果使用的是Microsoft.ApplicationInsights.SnapshotCollector NuGet 包版本 1.3.5 或更高版本,则将以下 using 语句添加到 Startup.csIf Microsoft.ApplicationInsights.SnapshotCollector NuGet package version 1.3.5 or above is used, then add the following using statements to Startup.cs.

           using Microsoft.ApplicationInsights.SnapshotCollector;
      

      Startup.csStartup 类的 ConfigureServices 方法末尾添加以下内容。Add the following at the end of the ConfigureServices method in the Startup class in Startup.cs.

           services.AddSnapshotCollector((configuration) => Configuration.Bind(nameof(SnapshotCollectorConfiguration), configuration));
      
    2. 如果使用的是Microsoft.ApplicationInsights.SnapshotCollector NuGet 包版本 1.3.4 或更低版本,则将以下 using 语句添加到 Startup.csIf Microsoft.ApplicationInsights.SnapshotCollector NuGet package version 1.3.4 or below is used, then add the following using statements to Startup.cs.

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

      将以下 SnapshotCollectorTelemetryProcessorFactory 类添加到 Startup 类。Add the following SnapshotCollectorTelemetryProcessorFactory class to Startup class.

      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 服务添加到启动管道:Add the SnapshotCollectorConfiguration and SnapshotCollectorTelemetryProcessorFactory services to the startup pipeline:

         // 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 节来自定义快照调试器配置。If needed, customized the Snapshot Debugger configuration by adding a SnapshotCollectorConfiguration section to appsettings.json. 快照调试器配置中的所有设置都是可选的。All settings in the Snapshot Debugger configuration are optional. 以下示例显示与默认配置等效的配置:Here is an example showing a configuration equivalent to the default configuration:

    {
      "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 应用程序配置快照集合Configure snapshot collection for other .NET applications

  1. 如果尚未在 Application Insights 上检测到你的应用程序,请先启用 Application Insights 并设置检测密钥If your application isn't already instrumented with Application Insights, get started by enabling Application Insights and setting the instrumentation key.

  2. Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。Add the Microsoft.ApplicationInsights.SnapshotCollector NuGet package in your app.

  3. 仅当向 Application Insights 报告了异常时,才收集快照。Snapshots are collected only on exceptions that are reported to Application Insights. 可能需要修改代码才能报告。You may need to modify your code to report them. 异常处理代码取决于应用程序的结构,示例如下:The exception handling code depends on the structure of your application, but an example is below:

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

后续步骤Next steps

  • 为应用程序生成可触发异常的流量。Generate traffic to your application that can trigger an exception. 然后等待 10 到 15 分钟,这样快照就会发送到 Application Insights 实例。Then, wait 10 to 15 minutes for snapshots to be sent to the Application Insights instance.
  • 请参见 Azure 门户中的快照See snapshots in the Azure portal.
  • 排查 Snapshot Debugger 问题时如需帮助,请参阅 Snapshot Debugger 故障排除For help with troubleshooting Snapshot Debugger issues, see Snapshot Debugger troubleshooting.