ApplicationInsights.config: do you still need it, and what replaced it

The file is a relic of a time when the .NET SDK was a set of plug-ins wired together in XML. That design made sense for IIS apps you couldn’t easily recompile; it makes less sense now that the SDK is OpenTelemetry underneath. Knowing what each section did is still the fastest way to migrate it.

What the file configured

In SDK 2.x for ASP.NET, the file described the whole telemetry pipeline. Its top-level sections:

A trimmed 2.x file, as Microsoft’s own template lays it out:

<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
  <TelemetryInitializers>
    <Add Type="Microsoft.ApplicationInsights.Web.OperationNameTelemetryInitializer, Microsoft.AI.Web" />
    <!-- ...more initializers... -->
  </TelemetryInitializers>
  <TelemetryModules>
    <Add Type="Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule, Microsoft.AI.Web" />
    <!-- ...more modules... -->
  </TelemetryModules>
  <TelemetrySinks>
    <Add Name="default">
      <TelemetryProcessors>
        <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
          <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
        </Add>
      </TelemetryProcessors>
      <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel" />
    </Add>
  </TelemetrySinks>
  <ConnectionString>InstrumentationKey=...;IngestionEndpoint=https://...</ConnectionString>
</ApplicationInsights>

Each <Add Type="…"> names a class and its assembly; child elements set public properties on it. That’s why the same file also carried settings such as the custom performance counter list and the handlers the request module should ignore.

Classic SDK 2.x

The .NET Classic API SDK 2.x is deprecated and retires on March 31, 2027. Until then, this is how the file behaves.

Who reads it, and where it lives

The file is named ApplicationInsights.config or ApplicationInsights.xml, depending on the application type, and it’s added to your project when you install most versions of the SDK. Visual Studio’s Add > Application Insights Telemetry creates it in the project root, and the build copies it to the bin folder. The Application Insights Agent adds one to web apps it instruments on IIS. Installing only the core Microsoft.ApplicationInsights package doesn’t create it.

Microsoft’s current documentation doesn’t describe a search order beyond that; its one instruction is to make sure the file is in your output directory and contains your latest changes. If a change seems to have no effect, compare the copy in bin with the one in source control first.

Two cases ignore the file entirely: the App Service Application Insights extension, and the extension for Azure VMs and virtual machine scale sets.

What goes wrong with it

• A typo can silence everything. Microsoft warns that if the file references a type or property that doesn’t exist, the SDK may silently fail to send any telemetry. Check type and assembly names character by character.
• Upgrades rewrite it. The template’s own comments warn that custom handler lists, counters and heartbeat exclusions “will be lost upon NuGet upgrade”. Diff the file after every SDK update.
• Sampling lives here too. The default file registers two AdaptiveSamplingTelemetryProcessor nodes, one for Event items and one for everything else, each targeting five items per second. Deleting them while tidying the file switches sampling off, which shows up as a jump in ingestion and cost a day later.
• Code and file both configure TelemetryConfiguration.Active. Settings made in Application_Start and settings in the file act on the same object; keep each setting in one place.

ASP.NET Core never used it

ASP.NET Core has no ApplicationInsights.config. Configuration happens through dependency injection, and changing TelemetryConfiguration.Active isn’t supported there. The 2.x equivalents of each section:

// Program.cs, Application Insights SDK 2.x for ASP.NET Core
builder.Services.AddApplicationInsightsTelemetry(options =>
{
    options.ConnectionString = builder.Configuration["ApplicationInsights:ConnectionString"];
    options.EnableAdaptiveSampling = true;          // processor chain default
});
builder.Services.AddSingleton<ITelemetryInitializer, MyInitializer>();            // <TelemetryInitializers>
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFilter>();             // <TelemetryProcessors>
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>(      // <TelemetryModules>
    (module, o) => module.EnableW3CHeadersInjection = true);

Worker Service apps follow the same pattern with AddApplicationInsightsTelemetryWorkerService().

Today: SDK 3.x and the Microsoft OpenTelemetry Distro

SDK 3.x keeps a smaller file

Microsoft.ApplicationInsights.Web 3.x, for ASP.NET on .NET Framework 4.6.2 or later, still reads applicationinsights.config, but the pipeline sections are gone. <TelemetryInitializers> and <TelemetryModules> are no longer supported, <InstrumentationKey> is replaced by <ConnectionString>, and the file becomes a flat list of switches:

<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
  <ConnectionString>InstrumentationKey=...;IngestionEndpoint=https://...</ConnectionString>
  <TracesPerSecond>5</TracesPerSecond>
  <StorageDirectory>C:\Logs</StorageDirectory>
  <EnableQuickPulseMetricStream>true</EnableQuickPulseMetricStream>
  <EnablePerformanceCounterCollectionModule>true</EnablePerformanceCounterCollectionModule>
  <EnableDependencyTrackingTelemetryModule>true</EnableDependencyTrackingTelemetryModule>
  <EnableRequestTrackingTelemetryModule>true</EnableRequestTrackingTelemetryModule>
</ApplicationInsights>

The 3.x schema also accepts DisableTelemetry, ApplicationVersion, SamplingRatio, DisableOfflineStorage, EnableTraceBasedLogsSampler and AddAutoCollectedMetricExtractor. Custom initializers and processors move to OpenTelemetry processors registered in code through TelemetryConfiguration.ConfigureOpenTelemetryBuilder; see telemetry initializers and their OpenTelemetry equivalents. TelemetryConfiguration.CreateFromConfiguration(string) was removed, and TelemetryConfiguration.Active with it: create configuration with CreateDefault().

SDK 3.x requires a connection string and can fail at startup without one. Don’t mix 2.x and 3.x packages in one app.

The Microsoft OpenTelemetry Distro has no file

The distro configures through its options object, standard OpenTelemetry environment variables and your own appsettings.json:

using Microsoft.OpenTelemetry;

builder.UseMicrosoftOpenTelemetry(options =>
{
    options.Exporters = ExportTarget.AzureMonitor;
    options.AzureMonitor.ConnectionString =
        builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]
        ?? builder.Configuration["AzureMonitor:ConnectionString"];
    options.AzureMonitor.TracesPerSecond = 5.0;
    options.AzureMonitor.EnableLiveMetrics = true;
    options.Instrumentation.EnableSqlClientInstrumentation = true;
});

Microsoft recommends the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable for production; an explicit value in code wins over it. Role name and instance come from OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES, and Node.js and Python select a sampler with OTEL_TRACES_SAMPLER. The connection string guide covers precedence in detail.

Moving a .NET Framework app off the 2.x file

For an ASP.NET app that has to stay on .NET Framework, the shortest supported path is SDK 3.x, and most of the work is in the file and the package list:

1. Remove the packages that have no 3.x version: Microsoft.ApplicationInsights.WindowsServer, ...WindowsServer.TelemetryChannel, ...DependencyCollector, ...PerfCounterCollector, ...EventCounterCollector and the logging adapters such as ...TraceListener. Their modules and initializers are the ones listed in your 2.x file.
2. Upgrade every remaining Application Insights package to 3.x at once, and target .NET Framework 4.6.2 or later.
3. Rewrite the file to the flat 3.x form: keep <ConnectionString>, delete <TelemetryInitializers>, <TelemetryModules> and <TelemetrySinks>, and turn the adaptive sampling settings into <TracesPerSecond> or <SamplingRatio>.
4. Port custom initializers and processors to OpenTelemetry processors registered in Application_Start.
5. Validate before you ship: turn on the SDK’s self-diagnostics log, or add the OpenTelemetry console exporter, and confirm requests, dependencies and logs still arrive.

Microsoft lists the full set of incompatible packages and breaking changes in its migration guide; a third-party package that depends on 2.x (Microsoft names Serilog.Sinks.ApplicationInsights as an example) has to support 3.x before you can upgrade.

Migration map

The sampling guide explains why the adaptive processor’s per-host target and the new traces-per-second default don’t behave identically.

Checklist when the file seems to be ignored

1. Is this ASP.NET on .NET Framework? Anything else doesn’t read it.
2. Is the copy in the output folder current?
3. Is the App Service or VM extension on? Then the file is ignored.
4. Does every Type attribute name a class and assembly that exist in the deployed bin folder?
5. On 3.x, does the file still contain <TelemetryInitializers> or <TelemetryModules>? Those sections no longer do anything.
6. Is a connection string present? 3.x won’t start without one.