适用于 ASP.NET Core 应用程序的 Application Insights

项目
08/28/2024

本文介绍如何为 ASP.NET Core 应用程序启用和配置 Application Insights。

注意

以下文档依赖于 Application Insights 经典 API。 Application Insights 的长期计划是使用 OpenTelemetry 收集数据。有关详细信息，请参阅为 .NET、Node.js、Python 和 Java 应用程序启用 Azure Monitor OpenTelemetry 和我们的 OpenTelemetry 路线图。迁移指导适用于 .NET、Node.js 和 Python。

Application Insights 可以从你的 ASP.NET Core 应用程序收集以下遥测数据：

请求
依赖项
异常
性能计数器
检测信号
日志

我们将使用一个 MVC 应用程序示例。如果你使用的是辅助角色服务，请使用适用于辅助角色服务应用程序的 Application Insights 中的说明。

提供基于 OpenTelemetry 的 .NET 产品/服务。有关详细信息，请参阅 OpenTelemetry 概述。

注意

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

注意

如果要使用独立的 ILogger 提供程序，请使用 Microsoft.Extensions.Logging.ApplicationInsight。

支持的方案

无论在何处以何种方式运行你的应用程序，适用于 ASP.NET Core 的 Application Insights SDK 都可对其进行监视。如果应用程序正在运行并与 Azure 建立了网络连接，则可以收集遥测数据。 Application Insights 监视在任何支持 .NET Core 的地方都受支持，并涵盖以下方案：

操作系统：Windows、Linux 或 Mac
托管方法：进程内或进程外
部署方法：框架依赖或自包含
Web 服务器：Internet Information Server (IIS) 或 Kestrel
托管平台：Azure 应用服务的 Web 应用功能、Azure 虚拟机、Docker 和 Azure Kubernetes 服务 (AKS)
.NET 版本：所有并非处于预览状态的官方支持的 .NET 版本
IDE：Visual Studio、Visual Studio Code 或命令行

先决条件

需要：

一个正常运行的 ASP.NET Core 应用程序。如果需要创建 ASP.NET Core 应用程序，请遵循此 ASP.NET Core 教程。
对受支持版本的 Application Insights NuGet 包的引用。
一个有效的 Application Insights 连接字符串。将任何遥测数据发送到 Application Insights 时，都需要使用此字符串。如果你需要创建新的 Application Insights 资源来获取连接字符串，请参阅创建 Application Insights 资源。

启用 Application Insights 服务器端遥测 (Visual Studio)

对于 Visual Studio for Mac，请使用手动指南。只有 Windows 版本的 Visual Studio 支持此过程。

在 Visual Studio 中打开项目。
转到“项目”>“添加 Application Insights 遥测”。
选择“Azure Application Insights”>“下一步”。
选择订阅和 Application Insights 实例。也可使用“新建”创建一个新实例。选择“下一步”。
添加或确认 Application Insights 连接字符串。系统应该会根据你在上一步的选择对它进行预填充。选择“完成”。
将 Application Insights 添加到项目后，确认使用的是最新稳定版本的 SDK。转到“项目”>“管理 NuGet 包”>“Microsoft.ApplicationInsights.AspNetCore”。如果需要，请选择“更新”。

启用 Application Insights 服务器端遥测（不使用 Visual Studio）

安装适用于 ASP.NET Core 的 Application Insights SDK NuGet 包。

我们建议始终使用最新稳定版本。在开源 GitHub 存储库中可以找到 SDK 的完整发行说明。

以下代码示例演示了要添加到项目的 .csproj 文件中的更改：
```
<ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>
```

将 AddApplicationInsightsTelemetry() 添加到 startup.cs 或 program.cs 类。选择取决于 .NET Core 版本。

ASP.NET Core 6 及更高版本
ASP.NET Core 5 及更低版本

在 Program 类中的 WebApplication.CreateBuilder() 方法之后添加 builder.Services.AddApplicationInsightsTelemetry();，如以下示例所示：

// This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);

// The following line enables Application Insights telemetry collection.
builder.Services.AddApplicationInsightsTelemetry();

// This code adds other services for your application.
builder.Services.AddMvc();

var app = builder.Build();

将 services.AddApplicationInsightsTelemetry(); 添加到 Startup 类中的 ConfigureServices() 方法，如以下示例所示：

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // The following line enables Application Insights telemetry collection.
    services.AddApplicationInsightsTelemetry();

    // This code adds other services for your application.
    services.AddMvc();
}

注意

此 .NET 版本不再受支持。

设置连接字符串。

尽管你可以将连接字符串作为 AddApplicationInsightsTelemetry 的 ApplicationInsightsServiceOptions 参数的一部分提供，但我们建议你在配置中指定连接字符串。以下代码示例展示了如何在 appsettings.json 中指定连接字符串。在发布期间，请确保将 appsettings.json 复制到应用程序根文件夹。
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}
```
或者，在 APPLICATIONINSIGHTS_CONNECTION_STRING 环境变量或 JSON 配置文件中的 ApplicationInsights:ConnectionString 中指定连接字符串。

例如：
- SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
- SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
- 通常，APPLICATIONINSIGHTS_CONNECTION_STRING 用在 Web 应用中。它也可以在所有支持此 SDK 的地方使用。
注意

在代码中指定的连接字符串优先于环境变量 APPLICATIONINSIGHTS_CONNECTION_STRING，而后者又优先于其他选项。

用户机密和其他配置提供程序

如果你要将连接字符串存储在 ASP.NET Core 用户机密中，或者要从其他配置提供程序中检索它，可以将重载与 Microsoft.Extensions.Configuration.IConfiguration 参数一起使用。示例参数为 services.AddApplicationInsightsTelemetry(Configuration);。

在 Microsoft.ApplicationInsights.AspNetCore 版本 2.15.0 及更高版本中，调用 services.AddApplicationInsightsTelemetry() 会自动从应用程序的 Microsoft.Extensions.Configuration.IConfiguration 中读取连接字符串。无需显式提供 IConfiguration。

如果 IConfiguration 已从多个提供程序加载配置，则无论添加提供程序的顺序如何，services.AddApplicationInsightsTelemetry 都会优先考虑 appsettings.json 中的配置。使用 services.AddApplicationInsightsTelemetry(IConfiguration) 方法从 IConfiguration 读取配置，而无需对 appsettings.json 进行这种优先处理。

运行应用程序

运行应用程序并向其发出请求。现在，遥测数据应会流入 Application Insights。 Application Insights SDK 自动将传入的 Web 请求收集到应用程序，并收集以下遥测数据。

实时指标

实时指标可用于快速验证是否正确配置了使用 Application Insights 的应用程序监视。遥测数据可能需要几分钟才能出现在 Azure 门户中，但实时指标窗格会近乎实时地显示正在运行的进程的 CPU 使用情况。它还可以显示其他遥测，例如请求、依赖项和跟踪。

使用代码为任何 .NET 应用程序启用实时指标

注意

按照建议用于 .NET 应用程序的说明加入实时指标时，将会默认启用它。

若要手动配置实时指标，请执行以下操作：

安装 NuGet 包 Microsoft.ApplicationInsights.PerfCounterCollector。
以下示例控制台应用代码显示了如何设置实时指标：

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

上述示例适用于控制台应用，但在所有 .NET 应用程序中都可以使用相同的代码。如果启用了自动收集遥测数据的任何其他遥测模块，请务必确保用于初始化这些模块的相同配置也用于实时指标模块。

ILogger 日志

默认配置收集 ILogger Warning 日志和严重性级别更高的日志。有关详细信息，请参阅如何自定义 ILogger 日志收集？。

依赖项

默认情况已启用依赖项收集。 Application Insights 中的依赖项跟踪介绍了自动收集的依赖项，以及执行手动跟踪的步骤。

性能计数器

对 ASP.NET Core 中的性能计数器的支持限制如下：

如果应用程序在 Web 应用 (Windows) 中运行，则 SDK 2.4.1 和更高版本将收集性能计数器。
如果应用程序在 Windows 中运行且面向的是 netstandard2.0 或更高版本，则 SDK 版本 2.7.1 及更高版本将收集性能计数器。
对于面向 .NET Framework 的应用程序，所有版本的 SDK 都支持性能计数器。
SDK 2.8.0 及更高版本在 Linux 中支持 CPU/内存计数器。但不在 Linux 中支持其他计数器。若要获取 Linux 和其他非 Windows 环境中的系统计数器，请使用 EventCounter。

EventCounter

默认情况下，启用 EventCounterCollectionModule。若要了解如何配置要收集的计数器列表，请参阅 EventCounters 简介。

通过 HTTP 扩充数据

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

为 Web 应用程序启用客户端遥测

完成前面所述的步骤足以开始收集服务器端遥测数据。如果应用程序具有客户端组件，请按照后续步骤开始使用 JavaScript (Web) SDK 加载程序脚本注入通过配置来收集用量遥测数据。

在 _ViewImports.cshtml 中添加注入代码：

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

在 _Layout.cshtml 中，将 HtmlHelper 插入到 <head> 节的末尾、任何其他脚本的前面。若要从页面报告任何自定义 JavaScript 遥测数据，请将其注入到此片段的后面：
```
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
```

作为 FullScript 的替代方法，ScriptBody 从 Application Insights SDK for ASP.NET Core 版本 2.14 开始提供。如果需要控制 <script> 标记以设置内容安全策略，请使用 ScriptBody：

<script> // apply custom changes to this script tag.
 @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

前面引用的 .cshtml 文件名取自默认的 MVC 应用程序模板。从根本上讲，若要为应用程序正确启用客户端监视，JavaScript (Web) SDK 加载程序脚本必须出现在所要监视的应用程序的每个页面的 <head> 部分中。在应用程序模板中，将 JavaScript (Web) SDK 加载程序脚本添加到 _Layout.cshtml 以启用客户端监视。

如果你的项目不包含 _Layout.cshtml，仍可通过将 JavaScript (Web) SDK 加载程序脚本添加到控制应用内所有页面的 <head> 的等效文件来添加客户端监视。或者，可将 JavaScript (Web) SDK 加载程序脚本添加到多个页面中，但我们不建议这样做。

注意

JavaScript 注入提供默认配置体验。除了设置连接字符串以外，如果还需要其他配置，你需要删除所述的自动注入并手动添加 JavaScript SDK。

配置 Application Insights SDK

可以自定义适用于 ASP.NET Core 的 Application Insights SDK 以更改默认配置。 Application Insights SDK ASP.NET 的用户可以使用 ApplicationInsights.config 或通过修改 TelemetryConfiguration.Active 来熟悉配置更改。对于 ASP.NET Core，除非另有说明，否则在 Startup.cs 类的 ConfigureServices() 方法中进行几乎所有配置更改。以下部分提供了详细信息。

注意

在 ASP.NET Core 应用程序中，不支持通过修改 TelemetryConfiguration.Active 来更改配置。

使用 ApplicationInsightsServiceOptions

可以通过向 AddApplicationInsightsTelemetry 传递 ApplicationInsightsServiceOptions 来修改一些通用设置，如以下示例所示：

ASP.NET Core 6 及更高版本
ASP.NET Core 5 及更低版本

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions aiOptions
                = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables live metrics (also known as QuickPulse).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetry(aiOptions);
}

注意

此 .NET 版本不再受支持。

此表包含 ApplicationInsightsServiceOptions 设置的完整列表：

设置	说明	默认
EnablePerformanceCounterCollectionModule	启用/禁用 `PerformanceCounterCollectionModule`。	True
EnableRequestTrackingTelemetryModule	启用/禁用 `RequestTrackingTelemetryModule`。	True
EnableEventCounterCollectionModule	启用/禁用 `EventCounterCollectionModule`。	True
EnableDependencyTrackingTelemetryModule	启用/禁用 `DependencyTrackingTelemetryModule`。	True
EnableAppServicesHeartbeatTelemetryModule	启用/禁用 `AppServicesHeartbeatTelemetryModule`。	True
EnableAzureInstanceMetadataTelemetryModule	启用/禁用 `AzureInstanceMetadataTelemetryModule`。	True
EnableQuickPulseMetricStream	启用/禁用 LiveMetrics 功能。	正确
EnableAdaptiveSampling	启用/禁用自适应采样。	正确
EnableHeartbeat	启用/禁用检测信号功能。它定期（默认间隔为 15 分钟）发送名为 `HeartbeatState` 的自定义指标，其中包含有关运行时的信息，例如 .NET 版本、Azure 环境信息（如果适用）。	正确
AddAutoCollectedMetricExtractor	启用/禁用 `AutoCollectedMetrics extractor`。此遥测处理器在采样发生之前发送有关请求/依赖项的预聚合指标。	True
RequestCollectionOptions.TrackExceptions	启用/禁用请求收集模块的未经处理的异常跟踪报告。	在 `netstandard2.0` 中为 false（因为异常是通过 `ApplicationInsightsLoggerProvider` 跟踪的）。否则为 true。
EnableDiagnosticsTelemetryModule	启用/禁用 `DiagnosticsTelemetryModule`。禁用会导致以下设置被忽略：`EnableHeartbeat`、`EnableAzureInstanceMetadataTelemetryModule` 和 `EnableAppServicesHeartbeatTelemetryModule`。	True

有关最新列表，请参阅 ApplicationInsightsServiceOptions 中的可配置设置。

针对 Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 及更高版本的配置建议

在 Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 及更高版本中，配置 ApplicationInsightsServiceOptions 中提供的每个设置，包括 ConnectionString。使用应用程序的 IConfiguration 实例。设置必须位于 ApplicationInsights 节下，如以下示例所示。 appsettings.json 的以下节配置连接字符串，并禁用自适应采样和性能计数器收集。

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

如果使用 builder.Services.AddApplicationInsightsTelemetry(aiOptions) （适用于 ASP.NET Core 6.0）或 services.AddApplicationInsightsTelemetry(aiOptions)（适用于 ASP.NET Core 3.1 及更早版本），它会覆盖来自 Microsoft.Extensions.Configuration.IConfiguration 的设置。

采样

适用于 ASP.NET Core 的 Application Insights SDK 支持固定频率和自适应采样。默认情况下，启用自适应采样。

有关详细信息，请参阅配置 ASP.NET Core 应用程序的自适应采样。

添加 TelemetryInitializer

如果要使用其他信息来扩充遥测，请使用遥测初始化表达式。

将任何新的 TelemetryInitializer 添加到 DependencyInjection 容器，如以下代码所示。 SDK 会自动拾取添加到 DependencyInjection 容器的任何 TelemetryInitializer。

ASP.NET Core 6 及更高版本
ASP.NET Core 5 及更低版本

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

注意

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); 适用于简单的初始化程序。对于其他程序，builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); 是必需的。

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
}

注意

services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); 适用于简单的初始化程序。对于其他程序，services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); 是必需的。此 .NET 版本不再受支持。

删除 TelemetryInitializer

默认情况下，提供遥测初始化表达式。若要删除所有或特定的遥测初始化表达式，请在调用 AddApplicationInsightsTelemetry() 之后使用以下示例代码。

ASP.NET Core 6 及更高版本
ASP.NET Core 5 及更低版本

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // Remove a specific built-in telemetry initializer
    var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                        (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
    if (tiToRemove != null)
    {
        services.Remove(tiToRemove);
    }

    // Remove all initializers
    // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
    services.RemoveAll(typeof(ITelemetryInitializer));
}

注意

此 .NET 版本不再受支持。

添加遥测处理器

可以使用 IServiceCollection 中的扩展方法 AddApplicationInsightsTelemetryProcessor 将自定义遥测处理程序添加到 TelemetryConfiguration。在高级筛选方案中使用遥测处理器。使用以下示例：

ASP.NET Core 6 及更高版本
ASP.NET Core 5 及更低版本

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddApplicationInsightsTelemetry();
    services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

    // If you have more processors:
    services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
}

注意

此 .NET 版本不再受支持。

配置或删除默认 TelemetryModule

Application Insights 自动收集有关特定工作负荷的遥测数据，无需用户手动跟踪。

默认情况下，启用以下自动收集模块。这些模块负责自动收集遥测数据。可以禁用或配置这些模块，以改变其默认行为。

RequestTrackingTelemetryModule：从传入 Web 请求收集 RequestTelemetry。
DependencyTrackingTelemetryModule：从传出 HTTP 调用和 SQL 调用收集 DependencyTelemetry。
PerformanceCollectorModule：收集 Windows PerformanceCounter。
QuickPulseTelemetryModule：收集要在实时指标窗格中显示的遥测。
AppServicesHeartbeatTelemetryModule：收集有关托管应用程序的应用服务环境的检测信号（以自定义指标的形式发送）。
AzureInstanceMetadataTelemetryModule：收集有关托管应用程序的 Azure VM 环境的检测信号（以自定义指标的形式发送）。
EventCounterCollectionModule：收集 EventCounter。此模块是一项新功能，可在 SDK 2.8.0 及更高版本中使用。

若要配置任何默认的 TelemetryModule，请按以下示例所示使用 IServiceCollection 中的扩展方法 ConfigureTelemetryModule<T>：

ASP.NET Core 6 及更高版本
ASP.NET Core 5 及更低版本

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // The following configures DependencyTrackingTelemetryModule.
    // Similarly, any other default modules can be configured.
    services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
            {
                module.EnableW3CHeadersInjection = true;
            });

    // The following removes all default counters from EventCounterCollectionModule, and adds a single one.
    services.ConfigureTelemetryModule<EventCounterCollectionModule>(
            (module, o) =>
            {
                module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
            }
        );

    // The following removes PerformanceCollectorModule to disable perf-counter collection.
    // Similarly, any other default modules can be removed.
    var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
    if (performanceCounterService != null)
    {
        services.Remove(performanceCounterService);
    }
}

注意

此 .NET 版本不再受支持。

在版本 2.12.2 及更高版本中，ApplicationInsightsServiceOptions 包含一个简单选项，用于禁用任何默认模块。

配置遥测通道

默认遥测通道为 ServerTelemetryChannel。下面的示例演示如何对其进行替代。

ASP.NET Core 6 及更高版本
ASP.NET Core 5 及更低版本

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

using Microsoft.ApplicationInsights.Channel;

public void ConfigureServices(IServiceCollection services)
{
    // Use the following to replace the default channel with InMemoryChannel.
    // This can also be applied to ServerTelemetryChannel.
    services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

    services.AddApplicationInsightsTelemetry();
}

注意

此 .NET 版本不再受支持。

注意

如果要刷新缓冲区，请参阅刷新数据。例如，如果在关闭的应用程序中使用 SDK，可能需要刷新缓冲区。

动态禁用遥测

如果要有条件和动态地禁用遥测，可以在代码中的任何位置使用 ASP.NET Core 依赖项注入容器解析 TelemetryConfiguration 实例，并在其上设置 DisableTelemetry 标志。

ASP.NET Core 6 及更高版本
ASP.NET Core 5 及更低版本

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
{
    configuration.DisableTelemetry = true;
    ...
}

注意

此 .NET 版本不再受支持。

前面的代码示例阻止将遥测数据发送到 Application Insights。它不会阻止任何自动收集模块收集遥测数据。如果要删除特定的自动收集模块，请参阅删除遥测模块。

常见问题

本部分提供常见问题的解答。

Application Insights 是否支持 ASP.NET Core 3.1？

Microsoft 不再支持 ASP.NET Core 3.1。

Application Insights SDK for ASP.NET Core 版本 2.8.0 和 Studio 2019 或更高版本可与 ASP.NET Core 3.1 应用程序一起使用。

如何跟踪不会自动收集的遥测数据？

通过使用构造函数注入获取 TelemetryClient 的实例，然后对其调用所需的 TrackXXX() 方法。不建议在 ASP.NET Core 应用程序中创建新的 TelemetryClient 或 TelemetryConfiguration 实例。 DependencyInjection 容器中已注册了TelemetryClient 的单一实例，该实例与剩余的遥测共享 TelemetryConfiguration。创建新 TelemetryClient 实例的前提是它需要的配置不同于剩余的遥测。

以下示例展示了如何从控制器跟踪更多遥测数据。

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

有关 Application Insights 中自定义数据报告的详细信息，请参阅 Application Insights 自定义指标 API 参考。使用 GetMetric API 将自定义指标发送到 Application Insights 时，可使用类似的方法。

如何捕获遥测中的请求和响应正文？

ASP.NET Core 提供通过 ILogger 记录 HTTP 请求/响应信息（包括正文）的内置支持。建议利用此功能。这可能会公开遥测中的个人身份信息 (PII)，并可能导致成本（性能成本和 Application Insights 计费）显著增加，因此请在使用此功能之前仔细评估风险。

如何自定义 ILogger 日志收集？

Application Insights 的默认设置是仅捕获“警告”和更严重的日志。

请更改 Application Insights 提供程序的日志记录配置以捕获“信息”和严重性低的日志，如下所示。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

请务必注意，以下示例不会导致 Application Insights 提供程序捕获 Information 日志。它不会对其进行捕获，因为 SDK 添加了一个默认日志记录筛选器，该筛选器指示 ApplicationInsights 仅捕获 Warning 日志和严重级别更高的日志。 Application Insights 需要显式替代。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

有关详细信息，请参阅 ILogger 配置。

某些 Visual Studio 模板使用 IWebHostBuilder 中的 UseApplicationInsights() 扩展方法来启用 Application Insights。这种用法是否仍然有效？

尽管 UseApplicationInsights() 扩展方法仍受支持，但它在 Application Insights SDK 版本 2.8.0 和更高版本中已标记为弃用。在下一个 SDK 主要版本中，将会删除它。若要启用 Application Insights 遥测，请使用 AddApplicationInsightsTelemetry()，因为它提供用于控制一些配置的重载。此外，在 ASP.NET Core 3.X 应用中，services.AddApplicationInsightsTelemetry() 是启用 Application Insights 的唯一方式。

我正在将 ASP.NET Core 应用程序部署到 Web 应用。是否仍要从 Web 应用启用 Application Insights 扩展？

如果在生成时已按本文所示安装了 SDK，则无需从应用服务门户启用 Application Insights 扩展。如果安装了扩展，则当检测到 SDK 已添加时，该扩展将回退。如果从扩展启用 Application Insights，则无需安装和更新 SDK。但是，遵照本文中的说明启用 Application Insights 会更灵活，原因如下：

Application Insights 遥测功能在以下位置或模式下继续运行：
- 所有操作系统，包括 Windows、Linux 和 Mac。
- 所有发布模式，包括“独立”或“框架相关”。
- 所有目标框架，包括完整的 .NET Framework。
- 所有托管选项，包括 Web 应用、VM、Linux、容器、AKS和非 Azure 托管。
- 所有 .NET Core 版本，包括预览版。
从 Visual Studio 调试时，可在本地查看遥测数据。
可以使用 TrackXXX() API 跟踪更多自定义遥测数据。
可以完全控制配置。

是否可以使用 Azure Monitor Application Insights 代理（以前称为“状态监视器 v2”）等工具启用 Application Insights 监视？

是的。在 Application Insights Agent 2.0.0-beta1 及更高版本中，支持在 IIS 中托管的 ASP.NET Core 应用程序。

如果在 Linux 中运行应用程序，是否支持所有功能？

是的。 SDK 的功能支持在所有平台中是相同的，不过存在以下例外情况：

该 SDK 在 Linux 上收集事件计数器，因为性能计数器仅在 Windows 中受支持。大多数指标是相同的。

辅助角色服务是否支持此 SDK？

否。请为辅助角色服务使用适用于辅助角色服务应用程序（非 HTTP 应用）的 Application Insights。

如何卸载 SDK？

要删除 Application Insights，需要从应用程序中的 API 删除 NuGet 包和引用。可以使用 Visual Studio 中的 NuGet 包管理器卸载 NuGet 包。

注意

这些说明用于卸载 ASP.NET Core SDK。如果需要卸载 ASP.NET SDK，请参阅如何卸载 ASP.NET SDK？。

使用 NuGet 包管理器卸载 Microsoft.ApplicationInsights.AspNetCore 包。
若要完全删除 Application Insights，请检查并手动删除添加的代码或文件以及在项目中添加的所有 API 调用。有关详细信息，请参阅添加 Application Insights SDK 时会创建哪些内容？。

添加 Application Insights SDK 时会创建哪些内容？

将 Application Insights 添加到项目时，它会创建文件并在某些文件中添加代码。仅卸载 NuGet 包的话，并不会总是丢弃文件和代码。若要完全删除 Application Insights，应检查并手动删除添加的代码或文件以及在项目中添加的所有 API 调用。

将 Application Insights 遥测添加到 Visual Studio ASP.NET Core 模板项目时，它会添加以下代码：

[项目名称].csproj

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-ChinaNorth/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
  </ItemGroup>

  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>

Appsettings.json：

"ApplicationInsights": {
    "InstrumentationKey": "00000000-0000-0000-0000-000000000000"

ConnectedService.json

{
  "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
  "Version": "16.0.0.0",
  "GettingStartedDocument": {
    "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
  }
}

Startup.cs

   public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddApplicationInsightsTelemetry(); // This is added
        }

如何禁用遥测关联？

若要在代码中禁用遥测关联，请参阅 Application Insights 中的 <ExcludeComponentCorrelationHttpHeadersOnDomains>，了解控制台应用程序。

故障排除

请参阅专用疑难解答文章。

测试应用程序主机与引入服务之间的连接性

Application Insights SDK 和代理发送遥测，将其作为 REST 调用引入到引入终结点。可以使用原始 REST 客户端通过 PowerShell 或使用 curl 命令，测试从 Web 服务器或应用程序主机计算机到引入服务终结点的连接。请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

开源 SDK

阅读代码或为其做出贡献

有关最新的更新和 bug 修补程序，请参阅发行说明。

发行说明

对于版本 2.12 及更高版本：.NET SDK（包括 ASP.NET、ASP.NET Core 和日志记录适配器）

我们的服务更新还总结了 Application Insights 的主要改进。

后续步骤

浏览用户流，了解用户如何在应用中移动。
配置快照收集，以便在引发异常时查看源代码和变量的状态。
使用 API 发送自己的事件和指标，以获取应用性能和使用情况的详细视图。
使用可用性测试以不断查看中国的应用。
了解 ASP.NET Core 中的依赖项注入。

通过

适用于 ASP.NET Core 应用程序的 Application Insights

支持的方案

先决条件

启用 Application Insights 服务器端遥测 (Visual Studio)

启用 Application Insights 服务器端遥测（不使用 Visual Studio）

用户机密和其他配置提供程序

运行应用程序

实时指标

使用代码为任何 .NET 应用程序启用实时指标

ILogger 日志

依赖项

性能计数器

EventCounter

通过 HTTP 扩充数据

为 Web 应用程序启用客户端遥测

配置 Application Insights SDK

使用 ApplicationInsightsServiceOptions

针对 Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 及更高版本的配置建议

采样

添加 TelemetryInitializer

删除 TelemetryInitializer

添加遥测处理器

配置或删除默认 TelemetryModule

配置遥测通道

动态禁用遥测

常见问题

Application Insights 是否支持 ASP.NET Core 3.1？

如何跟踪不会自动收集的遥测数据？

如何捕获遥测中的请求和响应正文？

如何自定义 ILogger 日志收集？

某些 Visual Studio 模板使用 IWebHostBuilder 中的 UseApplicationInsights() 扩展方法来启用 Application Insights。 这种用法是否仍然有效？

我正在将 ASP.NET Core 应用程序部署到 Web 应用。 是否仍要从 Web 应用启用 Application Insights 扩展？

是否可以使用 Azure Monitor Application Insights 代理（以前称为“状态监视器 v2”）等工具启用 Application Insights 监视？

如果在 Linux 中运行应用程序，是否支持所有功能？

辅助角色服务是否支持此 SDK？

如何卸载 SDK？

添加 Application Insights SDK 时会创建哪些内容？

如何禁用遥测关联？

故障排除

测试应用程序主机与引入服务之间的连接性

开源 SDK

发行说明

后续步骤

其他资源

某些 Visual Studio 模板使用 IWebHostBuilder 中的 UseApplicationInsights() 扩展方法来启用 Application Insights。这种用法是否仍然有效？

我正在将 ASP.NET Core 应用程序部署到 Web 应用。是否仍要从 Web 应用启用 Application Insights 扩展？