@azure/mcp-linux-arm64 2.0.0-beta.9 → 2.0.0

package/dist/Instrumentation/Resources/migration/dotnet/aad-authentication-migration.md

@@ -0,0 +1,150 @@
+---
+title: AAD Authentication Migration (2.x to 3.x)
+category: migration
+applies-to: 3.x
+---
+
+# AAD Authentication Migration (2.x → 3.x)
+
+## What changed
+
+In 2.x, `SetAzureTokenCredential(object)` existed on `TelemetryConfiguration` but accepted an `object` parameter — it used reflection internally to avoid a hard dependency on `Azure.Core`. Some teams also used `IConfigureOptions<TelemetryConfiguration>` workarounds to configure credentials in DI scenarios.
+
+In 3.x, the method signature changed to **strongly typed** and new DI-friendly options were added:
+- `TelemetryConfiguration.SetAzureTokenCredential(TokenCredential)` — **Signature changed** from `object` to `TokenCredential`. Must be called before a `TelemetryClient` is created from that configuration.
+- `ApplicationInsightsServiceOptions.Credential` — **New in 3.x**. Preferred for DI scenarios (ASP.NET Core / Worker Service). Set your `TokenCredential` directly in the options lambda.
+
+Other key changes:
+- `TelemetryConfiguration.Active` — **Removed**. Use `TelemetryConfiguration.CreateDefault()` instead. Note: `CreateDefault()` now returns an internal static configuration (singleton-like) rather than a new instance each time.
+
+---
+
+## DI Scenario (ASP.NET Core / Worker Service)
+
+In 2.x, AAD auth in DI apps was commonly configured via `IConfigureOptions<TelemetryConfiguration>` workarounds. In 3.x, use the new `Credential` property on `ApplicationInsightsServiceOptions` directly — simpler and no extra class needed.
+
+### Before (2.x — IConfigureOptions pattern)
+
+```csharp
+using Microsoft.ApplicationInsights.Extensibility;
+using Microsoft.Extensions.Options;
+using Azure.Identity;
+
+public class TelemetryConfigurationEnricher : IConfigureOptions<TelemetryConfiguration>
+{
+    public void Configure(TelemetryConfiguration options)
+    {
+        // 2.x signature: SetAzureTokenCredential(object) — accepts object, uses reflection
+        object credential = new DefaultAzureCredential();
+        options.SetAzureTokenCredential(credential);
+    }
+}
+
+// In Startup.cs / Program.cs:
+services.AddSingleton<IConfigureOptions<TelemetryConfiguration>, TelemetryConfigurationEnricher>();
+services.AddApplicationInsightsTelemetry();
+```
+
+### After (3.x — Credential property on options)
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.ApplicationInsights.AspNetCore.Extensions;
+using Azure.Identity;
+
+builder.Services.AddApplicationInsightsTelemetry(options =>
+{
+    options.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+    options.Credential = new DefaultAzureCredential();
+});
+```
+
+### Migration steps (DI)
+
+1. **Remove the `IConfigureOptions<TelemetryConfiguration>` class** that calls `SetAzureTokenCredential()` (e.g., `TelemetryConfigurationEnricher`). Delete the entire class file if it only handled AAD auth.
+
+2. **Remove the DI registration** for the configurator:
+   ```csharp
+   // Delete this line:
+   services.AddSingleton<IConfigureOptions<TelemetryConfiguration>, TelemetryConfigurationEnricher>();
+   ```
+
+3. **Set the `Credential` property** in your `AddApplicationInsightsTelemetry()` options:
+   ```csharp
+   builder.Services.AddApplicationInsightsTelemetry(options =>
+   {
+       options.Credential = new DefaultAzureCredential();
+   });
+   ```
+
+4. For **Worker Service** apps, the same applies to `AddApplicationInsightsTelemetryWorkerService()`:
+   ```csharp
+   services.AddApplicationInsightsTelemetryWorkerService(options =>
+   {
+       options.Credential = new DefaultAzureCredential();
+   });
+   ```
+
+---
+
+## Non-DI Scenario (Console apps, manual TelemetryConfiguration)
+
+For apps that create `TelemetryConfiguration` directly (console apps, batch jobs, etc.), the new `SetAzureTokenCredential` method provides built-in AAD support. The main breaking change is that `TelemetryConfiguration.Active` is removed.
+
+### Before (2.x — TelemetryConfiguration.Active)
+
+```csharp
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.Extensibility;
+using Azure.Identity;
+
+var config = TelemetryConfiguration.Active;
+config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+// 2.x signature: SetAzureTokenCredential(object) — accepts object, uses reflection
+config.SetAzureTokenCredential((object)new DefaultAzureCredential());
+
+var client = new TelemetryClient(config);
+```
+
+### After (3.x — CreateDefault)
+
+```csharp
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.Extensibility;
+using Azure.Identity;
+
+var config = TelemetryConfiguration.CreateDefault();
+config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+// 3.x signature: SetAzureTokenCredential(TokenCredential) — strongly typed
+config.SetAzureTokenCredential(new DefaultAzureCredential());
+
+var client = new TelemetryClient(config);
+```
+
+### Migration steps (non-DI)
+
+1. **Replace `TelemetryConfiguration.Active`** with `TelemetryConfiguration.CreateDefault()` — the `Active` static property is removed in 3.x. Note that `CreateDefault()` returns an internal static configuration (singleton-like) rather than creating a new instance.
+
+2. **Use `SetAzureTokenCredential(TokenCredential)`** — the parameter type changed from `object` (2.x) to strongly typed `TokenCredential` (3.x). If your code previously cast to `object`, remove the cast. Call it **before** creating a `TelemetryClient` from that configuration.
+
+3. If using a custom `TokenCredential` (e.g., `ManagedIdentityCredential` with a specific client ID), pass it directly:
+   ```csharp
+   var credential = new ManagedIdentityCredential("your-client-id");
+   var config = TelemetryConfiguration.CreateDefault();
+   config.SetAzureTokenCredential(credential);
+   var client = new TelemetryClient(config);
+   ```
+
+---
+
+## Notes
+
+- The `Azure.Identity` package is still required — no change there.
+- If you previously used `SetAzureTokenCredential` conditionally (e.g., only in certain environments), apply the same condition when setting `options.Credential` (DI) or calling `SetAzureTokenCredential` (non-DI).
+- Both paths ultimately set `AzureMonitorExporterOptions.Credential` under the hood.
+
+## See also
+
+- [AddApplicationInsightsTelemetry API reference](learn://api-reference/dotnet/AddApplicationInsightsTelemetry.md) — full list of `ApplicationInsightsServiceOptions` properties
+- [UseAzureMonitor API reference](learn://api-reference/dotnet/UseAzureMonitor.md) — if migrating to Azure Monitor OpenTelemetry Distro instead
+- [App Insights 2.x → 3.x code migration](learn://migration/dotnet/appinsights-2x-to-3x-code-migration.md) — full migration guide

package/dist/Instrumentation/Resources/migration/dotnet/appinsights-2x-to-3x-code-migration.md

@@ -0,0 +1,164 @@
+---
+title: Application Insights 2.x to 3.x Migration
+category: migration
+applies-to: 3.x
+---
+
+# App Insights 2.x → 3.x Code Migration
+
+## What changed
+
+3.x uses OpenTelemetry under the hood. The main entry point is the same — `AddApplicationInsightsTelemetry()` — but several options and extension methods were removed.
+
+Key changes:
+- `InstrumentationKey` → use `ConnectionString`
+- `EnableAdaptiveSampling` → use `TracesPerSecond` (default `5`) or `SamplingRatio`
+- Logging is automatic — `ApplicationInsightsLoggerProvider` was removed
+- New: `Credential` for AAD authentication, `EnableTraceBasedLogsSampler` for log sampling control
+
+## Before / after
+
+**2.x**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+builder.Services.AddApplicationInsightsTelemetry(options =>
+{
+    options.InstrumentationKey = "your-ikey";          // Removed in 3.x
+    options.EnableAdaptiveSampling = false;             // Removed in 3.x
+    options.DeveloperMode = true;                       // Removed in 3.x
+});
+```
+
+**3.x**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.ApplicationInsights.AspNetCore.Extensions;
+
+builder.Services.AddApplicationInsightsTelemetry(options =>
+{
+    options.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+    options.SamplingRatio = 1.0f;       // No sampling (collect everything)
+    // DeveloperMode — no replacement needed, remove the line
+});
+```
+
+Or set `APPLICATIONINSIGHTS_CONNECTION_STRING` as an environment variable and call `AddApplicationInsightsTelemetry()` with no arguments.
+
+## Property changes
+
+| Property | Status | Action required |
+|---|---|---|
+| `ConnectionString` | Unchanged | None. |
+| `ApplicationVersion` | Unchanged | None. |
+| `EnableQuickPulseMetricStream` | Unchanged | None. Default `true`. |
+| `EnablePerformanceCounterCollectionModule` | Unchanged | None. Default `true`. |
+| `EnableDependencyTrackingTelemetryModule` | Unchanged | None. Default `true`. |
+| `EnableRequestTrackingTelemetryModule` | Unchanged | None. Default `true`. |
+| `AddAutoCollectedMetricExtractor` | Unchanged | None. Default `true`. |
+| `EnableAuthenticationTrackingJavaScript` | Unchanged | None. Default `false`. |
+| `InstrumentationKey` | **Removed** | Use `ConnectionString`. |
+| `EnableAdaptiveSampling` | **Removed** | Use `TracesPerSecond` or `SamplingRatio`. |
+| `DeveloperMode` | **Removed** | Delete the line. |
+| `EndpointAddress` | **Removed** | Endpoint is now part of `ConnectionString`. |
+| `EnableHeartbeat` | **Removed** | Delete the line; heartbeat is automatic. |
+| `EnableDebugLogger` | **Removed** | Delete the line. |
+| `RequestCollectionOptions` | **Removed** | Delete the line. |
+| `DependencyCollectionOptions` | **Removed** | Delete the line. |
+| `TelemetryInitializers` | **Removed** | Delete the line. |
+| `Credential` | **New** | `TokenCredential`, default `null`. Set for AAD auth. |
+| `TracesPerSecond` | **New** | `double?`, effective default `5`. Rate-limited sampling. |
+| `SamplingRatio` | **New** | `float?`, default `null`. Fixed-rate sampling (0.0–1.0). |
+| `EnableTraceBasedLogsSampler` | **New** | `bool?`, effective default `true`. Logs follow parent trace sampling. |
+
+## Removed extension methods
+
+| Method | Replacement |
+|---|---|
+| `AddApplicationInsightsTelemetry(string instrumentationKey)` | Use parameterless overload + `ConnectionString` in options or env var. |
+| `UseApplicationInsights()` (all `IWebHostBuilder` overloads) | Use `AddApplicationInsightsTelemetry()` on `IServiceCollection`. |
+| `AddApplicationInsightsTelemetryProcessor<T>()` | Use OpenTelemetry processors. |
+| `ConfigureTelemetryModule<T>()` | Removed; module functionality is built-in. |
+
+## Removed interfaces and classes
+
+| Type | Notes |
+|---|---|
+| `ITelemetryInitializer` | Removed. Convert to `BaseProcessor<Activity>` with `OnStart`. Register via `.AddProcessor<T>()` in the OpenTelemetry pipeline. |
+| `ITelemetryProcessor` | Removed. Convert to `BaseProcessor<Activity>` with `OnEnd`. To drop telemetry, clear `data.ActivityTraceFlags &= ~ActivityTraceFlags.Recorded`. Register via `.AddProcessor<T>()`. |
+| `ApplicationInsightsLoggerProvider` | Logging is now automatic. No replacement needed. |
+| `ExceptionTrackingMiddleware` | Exception tracking is built-in. |
+
+## TelemetryClient changes
+
+| Change | Details |
+|---|---|
+| `TrackEvent` | 3-param overload `(string, IDictionary<string,string>, IDictionary<string,double>)` **removed** — metrics dict dropped. Use 2-param overload and track metrics separately via `TrackMetric()`. |
+| `TrackException` | 3-param overload with `IDictionary<string,double>` **removed**. Use 2-param overload and track metrics separately via `TrackMetric()`. |
+| `TrackAvailability` | 8-param overload with trailing `IDictionary<string,double>` **removed**. Use 7-param overload and track metrics separately via `TrackMetric()`. |
+| `TrackPageView` | **Removed entirely** (both overloads). Use `TrackEvent` or `TrackRequest` instead. |
+| `GetMetric` | `MetricConfiguration` and `MetricAggregationScope` params **removed** from all overloads. Use simplified `GetMetric(metricId, ...)`. |
+| parameterless `TelemetryClient()` | **Removed**. Use `TelemetryClient(TelemetryConfiguration)` via DI. |
+| `client.InstrumentationKey` | **Removed**. Use `TelemetryConfiguration.ConnectionString`. |
+| `TrackTrace`, `TrackMetric`, `TrackRequest`, `TrackDependency` (full overload), `Flush` | **Unchanged** — no action needed. |
+
+## Middleware telemetry access
+
+In 2.x, middleware could access `RequestTelemetry` via `HttpContext.Features`:
+
+```csharp
+// 2.x
+var requestTelemetry = context.Features.Get<RequestTelemetry>();
+requestTelemetry?.Properties.Add("ResponseBody", responseBody);
+```
+
+In 3.x, `RequestTelemetry` is no longer placed in `HttpContext.Features`. Use `Activity.Current` instead:
+
+```csharp
+// 3.x
+using System.Diagnostics;
+
+var activity = Activity.Current;
+activity?.SetTag("ResponseBody", responseBody);
+```
+
+This applies to any code that accessed `RequestTelemetry` or `DependencyTelemetry` via `HttpContext.Features.Get<T>()`.
+
+## Manually constructed telemetry objects
+
+Telemetry types (`RequestTelemetry`, `DependencyTelemetry`, `TraceTelemetry`, `EventTelemetry`, `ExceptionTelemetry`, `MetricTelemetry`, `AvailabilityTelemetry`) still exist in 3.x and can be passed to `TelemetryClient.Track*(...)`. However:
+
+- `ISupportProperties` — **Removed**. Use the typed `Properties` dictionary directly on each telemetry class.
+- Type checks (`telemetry is RequestTelemetry`) in custom middleware or filters — these still compile but may not match auto-collected telemetry in contexts where the 3.x SDK uses `Activity` internally. Prefer `Activity.Current?.SetTag()` for enrichment.
+- `new DependencyTelemetry(...)` with `StartOperation<DependencyTelemetry>()` — **Still works**. The dependency is correlated automatically.
+
+## Migration steps
+
+1. Update the package:
+   ```xml
+   <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="3.*" />
+   ```
+
+2. Find and replace in your code:
+   - `InstrumentationKey = "..."` → `ConnectionString = "InstrumentationKey=...;IngestionEndpoint=..."`
+   - `EnableAdaptiveSampling = false` → `SamplingRatio = 1.0f` (or set `TracesPerSecond`)
+   - Delete any lines setting `DeveloperMode`, `EndpointAddress`, `EnableHeartbeat`, `EnableDebugLogger`, `RequestCollectionOptions`, `DependencyCollectionOptions`, or `TelemetryInitializers`
+   - Delete calls to `UseApplicationInsights()`, `AddApplicationInsightsTelemetryProcessor<T>()`, `ConfigureTelemetryModule<T>()`
+
+3. Migrate custom telemetry types:
+   - Convert each `ITelemetryInitializer` implementation to a `BaseProcessor<Activity>` with `OnStart`. Register via `.AddProcessor<T>()` in the OpenTelemetry pipeline.
+   - Convert each `ITelemetryProcessor` implementation to a `BaseProcessor<Activity>` with `OnEnd`. To drop telemetry, clear the Recorded flag: `data.ActivityTraceFlags &= ~ActivityTraceFlags.Recorded`. Register via `.AddProcessor<T>()`.
+   - `TelemetryClient` mostly works in 3.x but has breaking changes: remove `IDictionary<string, double> metrics` parameter from `TrackEvent`/`TrackException`/`TrackAvailability` calls (track metrics separately via `TrackMetric()`). Replace `TrackPageView` with `TrackEvent` or `TrackRequest`. Remove `GetMetric` overloads that take `MetricConfiguration`/`MetricAggregationScope`.
+
+4. Build and verify — the `Enable*` flags (`EnableQuickPulseMetricStream`, `EnableDependencyTrackingTelemetryModule`, etc.) still work with the same defaults. No changes needed for those.
+
+## Behavior notes
+
+- `TracesPerSecond` is the default sampling mode (effective default `5`). No configuration needed for most apps.
+- Connection string resolution order: `ApplicationInsightsServiceOptions.ConnectionString` → `APPLICATIONINSIGHTS_CONNECTION_STRING` env var → `ApplicationInsights:ConnectionString` in config.
+
+## See also
+
+- No-code-change migration(see in appinsights-2x-to-3x-no-code-change.md)
+- AddApplicationInsightsTelemetry API reference(see in AddApplicationInsightsTelemetry.md)
+- TelemetryClient breaking changes(see in TelemetryClient.md)

package/dist/Instrumentation/Resources/migration/dotnet/appinsights-2x-to-3x-no-code-change.md

@@ -0,0 +1,92 @@
+---
+title: Application Insights 2.x to 3.x — No-Code-Change Migration
+category: migration
+applies-to: 3.x
+---
+
+# App Insights 2.x → 3.x — No Code Change
+
+## When this applies
+
+Your migration requires **only a package upgrade** (no code changes) if both of these are true:
+
+1. You call `AddApplicationInsightsTelemetry()` with no arguments, an `IConfiguration`, or with options that only set **unchanged properties**.
+2. You do not use any **removed extension methods** (`UseApplicationInsights()`, `AddApplicationInsightsTelemetryProcessor<T>()`, `ConfigureTelemetryModule<T>()`).
+
+### Unchanged properties (safe to keep as-is)
+
+| Property | Default |
+|---|---|
+| `ConnectionString` | `null` |
+| `ApplicationVersion` | Entry assembly version |
+| `EnableQuickPulseMetricStream` | `true` |
+| `EnablePerformanceCounterCollectionModule` | `true` |
+| `EnableDependencyTrackingTelemetryModule` | `true` |
+| `EnableRequestTrackingTelemetryModule` | `true` |
+| `AddAutoCollectedMetricExtractor` | `true` |
+| `EnableAuthenticationTrackingJavaScript` | `false` |
+
+If your code only uses these properties (or none at all), **and** does not use `ITelemetryInitializer` or `ITelemetryProcessor`, no code changes are needed. (`TelemetryClient` still works in 3.x — existing usage does not block a no-code-change upgrade.)
+
+## Migration steps
+
+### 1. Update the package
+
+```xml
+<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="3.*" />
+```
+
+### 2. Build and run
+
+That's it. No code changes required.
+
+## Examples that work without changes
+
+**Parameterless call:**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddApplicationInsightsTelemetry();
+var app = builder.Build();
+```
+
+**IConfiguration overload:**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddApplicationInsightsTelemetry(builder.Configuration);
+var app = builder.Build();
+```
+
+**Options with only unchanged properties:**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.ApplicationInsights.AspNetCore.Extensions;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddApplicationInsightsTelemetry(options =>
+{
+    options.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+    options.EnableQuickPulseMetricStream = true;
+    options.EnableDependencyTrackingTelemetryModule = true;
+});
+var app = builder.Build();
+```
+
+All three examples above work identically in 2.x and 3.x.
+
+## What changes under the hood
+
+Even though your code stays the same, 3.x brings these improvements automatically:
+
+- Telemetry is now collected via OpenTelemetry — better standards alignment and ecosystem compatibility.
+- `TracesPerSecond` (effective default `5`) provides rate-limited sampling out of the box. No configuration needed.
+- Logging is integrated automatically — `ILogger` output is exported to Application Insights without additional setup.
+- Azure resource detection (App Service, VM) happens automatically.
+
+## See also
+
+- Application Insights 2.x to 3.x Code Migration(see in appinsights-2x-to-3x-code-migration.md)
+- AddApplicationInsightsTelemetry API reference(see in AddApplicationInsightsTelemetry.md)

package/dist/Instrumentation/Resources/migration/dotnet/aspnet-classic-2x-to-3x-code-migration.md

@@ -0,0 +1,190 @@
+---
+title: Classic ASP.NET 2.x to 3.x Migration
+category: migration
+applies-to: 3.x
+---
+
+# Classic ASP.NET 2.x → 3.x Code Migration
+
+## What changed
+
+3.x is built on OpenTelemetry internally. The NuGet package name stays the same — `Microsoft.ApplicationInsights.Web` — but the internal architecture changed. `applicationinsights.config` format is simplified, satellite packages are removed, and extensibility uses OpenTelemetry processors via `ConfigureOpenTelemetryBuilder`.
+
+Key changes:
+- `<InstrumentationKey>` → `<ConnectionString>` (connection string is **required** — 3.x throws without it)
+- `<TelemetryInitializers>`, `<TelemetryModules>`, `<TelemetryProcessors>` sections → removed entirely
+- `<TelemetryChannel>` section → removed (export managed by OpenTelemetry)
+- 12 satellite packages → removed (functionality built into the main package)
+- `TelemetryConfiguration.Active` → `TelemetryConfiguration.CreateDefault()` (returns static singleton in 3.x)
+- Minimum .NET Framework: 4.5.2 → **4.6.2**
+- Custom initializers/processors → OpenTelemetry processors via `ConfigureOpenTelemetryBuilder`
+
+## applicationinsights.config — before / after
+
+**2.x:**
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
+  <InstrumentationKey>00000000-0000-0000-0000-000000000000</InstrumentationKey>
+  <TelemetryInitializers>
+    <Add Type="Microsoft.ApplicationInsights.Web.WebTestTelemetryInitializer, Microsoft.AI.Web" />
+    <Add Type="Microsoft.ApplicationInsights.Web.SyntheticUserAgentTelemetryInitializer, Microsoft.AI.Web">
+      <Filters>search|spider|crawl|Bot|Monitor</Filters>
+    </Add>
+    <!-- ... more initializers ... -->
+  </TelemetryInitializers>
+  <TelemetryModules>
+    <Add Type="Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule, Microsoft.AI.Web" />
+    <Add Type="Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule, Microsoft.AI.Web" />
+    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector" />
+    <!-- ... more modules ... -->
+  </TelemetryModules>
+  <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
+    <DeveloperMode>false</DeveloperMode>
+  </TelemetryChannel>
+</ApplicationInsights>
+```
+
+**3.x:**
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
+  <ConnectionString>InstrumentationKey=...;IngestionEndpoint=https://dc.applicationinsights.azure.com/</ConnectionString>
+  <TracesPerSecond>5.0</TracesPerSecond>
+  <EnableTraceBasedLogsSampler>true</EnableTraceBasedLogsSampler>
+  <EnableQuickPulseMetricStream>true</EnableQuickPulseMetricStream>
+  <EnablePerformanceCounterCollectionModule>true</EnablePerformanceCounterCollectionModule>
+  <EnableDependencyTrackingTelemetryModule>true</EnableDependencyTrackingTelemetryModule>
+  <EnableRequestTrackingTelemetryModule>true</EnableRequestTrackingTelemetryModule>
+  <AddAutoCollectedMetricExtractor>true</AddAutoCollectedMetricExtractor>
+</ApplicationInsights>
+```
+
+## Web.config changes
+
+**Remove** `TelemetryCorrelationHttpModule` (OpenTelemetry handles correlation natively).
+
+**Keep** `ApplicationInsightsHttpModule` — still needed in 3.x.
+
+**Add** `TelemetryHttpModule` (from `OpenTelemetry.Instrumentation.AspNet`) — added automatically by NuGet install.
+
+## Satellite packages to remove
+
+These packages are no longer needed — their functionality is built into `Microsoft.ApplicationInsights.Web` 3.x. **Remove in this order** (dependents before dependencies):
+
+1. `Microsoft.ApplicationInsights.WindowsServer`
+2. `Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel`
+3. `Microsoft.ApplicationInsights.DependencyCollector`
+4. `Microsoft.ApplicationInsights.PerfCounterCollector`
+5. `Microsoft.ApplicationInsights.Agent.Intercept`
+6. `Microsoft.AspNet.TelemetryCorrelation`
+
+Also remove if present (skip any not in packages.config):
+- `Microsoft.ApplicationInsights.EventCounterCollector`
+- `Microsoft.Extensions.Logging.ApplicationInsights`
+- `Microsoft.ApplicationInsights.Log4NetAppender`
+- `Microsoft.ApplicationInsights.TraceListener`
+- `Microsoft.ApplicationInsights.DiagnosticSourceListener`
+- `Microsoft.ApplicationInsights.EtwCollector`
+- `Microsoft.ApplicationInsights.EventSourceListener`
+
+## TelemetryConfiguration changes
+
+| 2.x Pattern | 3.x Replacement |
+|---|---|
+| `TelemetryConfiguration.Active` | `TelemetryConfiguration.CreateDefault()` (returns static singleton) |
+| `new TelemetryConfiguration(ikey)` | `TelemetryConfiguration.CreateDefault()` + set `ConnectionString` |
+| `config.InstrumentationKey = "..."` | `config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=..."` |
+| `config.TelemetryInitializers.Add(...)` | Use `ConfigureOpenTelemetryBuilder` — see below |
+| `config.TelemetryProcessorChainBuilder` | Use `ConfigureOpenTelemetryBuilder` — see below |
+| `config.TelemetryChannel` | Removed — export managed by OpenTelemetry |
+| `config.TelemetrySinks` | Removed — use OpenTelemetry exporters |
+
+## Custom processor migration (non-DI)
+
+In classic ASP.NET, use `ConfigureOpenTelemetryBuilder` on `TelemetryConfiguration` in `Global.asax.cs`:
+
+```csharp
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.Extensibility;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Resources;
+
+public class MvcApplication : HttpApplication
+{
+    public static TelemetryClient TelemetryClient { get; private set; }
+
+    protected void Application_Start()
+    {
+        var config = TelemetryConfiguration.CreateDefault();
+        config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+        config.ConfigureOpenTelemetryBuilder(otel =>
+        {
+            otel.WithTracing(tracing =>
+            {
+                tracing.AddProcessor<MyEnrichmentProcessor>();
+                tracing.AddProcessor<MyFilterProcessor>();
+            });
+            otel.ConfigureResource(r => r.AddService("MyWebApp"));
+        });
+
+        TelemetryClient = new TelemetryClient(config);
+
+        AreaRegistration.RegisterAllAreas();
+        RouteConfig.RegisterRoutes(RouteTable.Routes);
+    }
+
+    protected void Application_End()
+    {
+        TelemetryClient?.Flush();
+        System.Threading.Tasks.Task.Delay(1000).Wait();
+    }
+}
+```
+
+> **Important:** Create a **single static** `TelemetryClient` instance in `Application_Start`. Do not create per-request or per-controller instances — this causes memory leaks and duplicate telemetry. `TelemetryConfiguration.CreateDefault()` returns a singleton that is shared with the `ApplicationInsightsHttpModule`.
+
+See TelemetryConfigurationBuilder.md for full API details.
+
+## Sampling changes
+
+- Per-type sampling (e.g. exclude exceptions from sampling) is **no longer supported**
+- Default: rate-limited at 5 traces/sec via `<TracesPerSecond>`
+- Fixed-rate: `<SamplingRatio>0.25</SamplingRatio>` (25%)
+- Custom OTel samplers not supported with 3.x shim
+
+## TelemetryClient changes
+
+See TelemetryClient.md for full breaking changes. Key items:
+- `TrackPageView` — removed entirely
+- `TrackEvent`/`TrackException`/`TrackAvailability` — metrics dict parameter removed
+- Parameterless `new TelemetryClient()` — removed, use `new TelemetryClient(TelemetryConfiguration.CreateDefault())`
+- `client.InstrumentationKey` — removed
+- Create a **single static instance** — do not create per-request (see processor migration section above)
+
+## Migration steps
+
+1. Check .NET Framework target — must be **4.6.2** or later
+2. Upgrade `Microsoft.ApplicationInsights.Web` to 3.x via Package Manager Console: `Update-Package Microsoft.ApplicationInsights.Web`
+3. Remove satellite packages via Package Manager Console in this order (dependents before dependencies):
+   - `Microsoft.ApplicationInsights.WindowsServer`
+   - `Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel`
+   - `Microsoft.ApplicationInsights.DependencyCollector`
+   - `Microsoft.ApplicationInsights.PerfCounterCollector`
+   - `Microsoft.ApplicationInsights.Agent.Intercept`
+   - `Microsoft.AspNet.TelemetryCorrelation`
+4. Rewrite `applicationinsights.config` to 3.x format (remove all `<TelemetryInitializers>`, `<TelemetryModules>`, `<TelemetryProcessors>`, `<TelemetryChannel>` sections; add `<ConnectionString>` and feature flags)
+5. Update `Web.config` — remove `TelemetryCorrelationHttpModule`, verify `TelemetryHttpModule` present
+6. Replace `TelemetryConfiguration.Active` with `TelemetryConfiguration.CreateDefault()` in code
+7. Create a single static `TelemetryClient` in `Application_Start`, flush in `Application_End`
+8. Migrate custom `ITelemetryInitializer`/`ITelemetryProcessor` to OpenTelemetry processors via `ConfigureOpenTelemetryBuilder`
+9. Fix TelemetryClient breaking calls (TrackEvent metrics dict, TrackPageView, etc.)
+10. Set `<ConnectionString>` in applicationinsights.config
+11. Build and verify
+
+## See also
+
+- ApplicationInsightsWeb API reference(see in ApplicationInsightsWeb.md)
+- ConfigureOpenTelemetryBuilder(see in TelemetryConfigurationBuilder.md)
+- TelemetryClient breaking changes(see in TelemetryClient.md)