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

项目
06/02/2023

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

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

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

如果尚未启用，请在 Web 应用中启用 Application Insights。
将 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。

如果需要，自定义添加到 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>

仅当向 Application Insights 报告了异常时，才收集快照。在某些情况下（例如，.NET 平台为较早版本时），可能需要配置异常收集，才能在门户的查看附带快照的异常。

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

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

注意

请确保应用程序引用 2.1.1 版或更新版本的 Microsoft.ApplicationInsights.AspNetCore 包。
将 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。

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

如果使用的是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));
```

如果使用的是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.
   }
}

如果需要，可通过在 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 应用程序配置快照集合

如果尚未在 Application Insights 上检测到你的应用程序，请先启用 Application Insights 并设置检测密钥。
将 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包添加到应用。

仅当向 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 故障排除。

通过

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

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

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

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

后续步骤

其他资源