【Azure Developer】ASP.NET Framework 4.8 集成 Azure Application Insights SDK 完整指南

在生产环境中应用性能监控是保障系统稳定运行的关键一环特别是部署到云上的服务但是由于.Net Framework 4.8项目年代久远无法实现一些无代码的方式集成获取日志数据。而Azure Application Insights提供了两种方式无代码 集成SDK的方式来实现日志收集。它提供了强大的请求追踪、依赖调用分析、异常捕获和性能指标收集能力。所以本文将详细介绍如何在 ASP.NET Framework 4.8 项目中集成 Application Insights SDK。选择正确的 SDK 版本ASP.NET Framework 与 ASP.NET Core 使用不同的 NuGet 包请勿混淆框架NuGet 包当前推荐版本ASP.NET Framework 4.6.2Microsoft.ApplicationInsights.Web2.22.xASP.NET CoreMicrosoft.ApplicationInsights.AspNetCore2.22.xWorker Service / ConsoleMicrosoft.ApplicationInsights.WorkerService2.22.x对于 .NET Framework 4.8 项目我们使用Microsoft.ApplicationInsights.Web。注意请使用Microsoft.ApplicationInsights.Web2.23.0安装该包后会自动引入以下组件Microsoft.ApplicationInsights— 核心 SDK提供 TelemetryClientMicrosoft.AI.Web— 自动追踪 HTTP 请求和响应Microsoft.AI.DependencyCollector— 自动追踪 SQL 查询、HTTP 外部调用等依赖项Microsoft.AI.PerfCounterCollector— 收集 CPU、内存等性能计数器Microsoft.AspNet.TelemetryCorrelation— 分布式追踪关联集成步骤第一步安装 NuGet 包在 Visual Studio 中打开 Package Manager Console执行Install-Package Microsoft.ApplicationInsights.Web -Version 2.23.0或者通过 NuGet Package Manager UI 搜索 Microsoft.ApplicationInsights.Web 并安装2.23.0版。第二步配置 Connection String安装完成后项目根目录会自动生成 ApplicationInsights.config 文件。打开该文件配置 Connection String?xml version1.0 encodingutf-8? ApplicationInsights xmlnshttp://schemas.microsoft.com/ApplicationInsights/2013/Settings ConnectionStringInstrumentationKeyxx-x-x-x-xxx;EndpointSuffixapplicationinsights.azure.cn;IngestionEndpointhttps://chinanorth3-0.in.applicationinsights.azure.cn/;LiveEndpointhttps://chinanorth3.livediagnostics.monitor.azure.cn/;AADAudiencehttps://monitor.azure.cn/;ApplicationId xx-x-x-x-xxx /ConnectionString TelemetryInitializers !-- 自动生成的初始化器配置 -- /TelemetryInitializers TelemetryModules !-- 自动生成的模块配置 -- /TelemetryModules /ApplicationInsightsPS示例使用的是中国区的Azure Application Insights 服务所以Connection String指向中国区 endpointIngestionEndpointhttps://dc.applicationinsights.azure.cn/;LiveEndpointhttps://live.applicationinsights.azure.cn/也可以使用环境变量 APPLICATIONINSIGHTS_CONNECTION_STRING来保存连接字符串。第三步验证 web.config 配置NuGet 包安装时会自动修改 web.config添加两个关键的 HTTP Module。请确认以下配置存在configuration system.webServer modules remove nameTelemetryCorrelationHttpModule / add nameTelemetryCorrelationHttpModule typeMicrosoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation preConditionmanagedHandler / remove nameApplicationInsightsWebTracking / add nameApplicationInsightsWebTracking typeMicrosoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web preConditionmanagedHandler / /modules /system.webServer /configuration提示这两个 Module 的顺序很重要 — TelemetryCorrelationHttpModule 必须在前负责分布式追踪的上下文传播。第四步发送自定义遥测数据可选SDK 安装后请求、依赖、异常等已自动收集。如需发送自定义事件或指标using Microsoft.ApplicationInsights; using Microsoft.ApplicationInsights.DataContracts; public class OrderController : Controller { private readonly TelemetryClient _telemetryClient new TelemetryClient(); … // 追踪自定义事件 _telemetryClient.TrackEvent(test event, new Dictionarystring, string { { event ID, Guid.NewGuid().ToString() }, { event Title, this is custome events title 20260514 } }); // 追踪自定义指标 _telemetryClient.TrackMetric(customer metrics, (new Random()).NextDouble()); … }第五步验证数据上报1. 本地运行项目触发几个页面请求2. 打开 Azure Portal → Application Insights 资源3. 进入Search确认能看到请求遥测数据4. 检查 Live Metrics确认实时数据流正常注意数据从应用发送到 Portal 通常有 2-5 分钟延迟Live Metrics 则是实时的。常见问题与注意事项1. App Service Auto-Instrumentation 冲突如果你的应用部署在 Azure App Service 上并且开启了 Application Insights 的 Auto-Instrumentation代码无侵入式监控不要同时在代码中安装 SDK。两者同时存在会导致重复的遥测数据性能下降依赖追踪异常解决方案二选一。推荐使用 SDK 方式更灵活可控并将 App Service 的 ApplicationInsightsAgent_EXTENSION_VERSION 设为 disabled。2. 采样配置生产环境中高流量场景下建议配置自适应采样以控制成本ApplicationInsights TelemetryProcessors Add TypeMicrosoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel MaxTelemetryItemsPerSecond5/MaxTelemetryItemsPerSecond /Add /TelemetryProcessors /ApplicationInsights3. 关于 OpenTelemetry 迁移微软目前推荐新项目使用 OpenTelemetry Azure.Monitor.OpenTelemetry.Exporter。但该方案目前仅支持 ASP.NET Core。对于 .NET Framework 4.8 项目Classic SDKMicrosoft.ApplicationInsights.Web仍是官方支持的方案短期内不会被废弃。4. SDK 诊断日志如遇到数据不上报的问题可开启 SDK 自诊断TelemetryModules Add TypeMicrosoft.ApplicationInsights.Extensibility.Implementation.Tracing.FileDiagnosticsTelemetryModule, Microsoft.ApplicationInsights SeverityVerbose/Severity LogFileNameai-sdk-diag.txt/LogFileName LogFilePathD:\home\LogFiles\ApplicationInsights/LogFilePath /Add /TelemetryModules总结步骤操作1安装 Microsoft.ApplicationInsights.Web NuGet 包2在 ApplicationInsights.config 中配置 Connection String或添加环境变量APPLICATIONINSIGHTS_CONNECTION_STRING3确认 web.config 中 HTTP Module 已正确注册4可选通过 TelemetryClient 发送自定义遥测5在 Azure Portal 验证数据上报