@azure/mcp-linux-arm64 2.0.0-beta.30 → 2.0.0-beta.31

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

@@ -102,6 +102,36 @@ Or set `APPLICATIONINSIGHTS_CONNECTION_STRING` as an environment variable and ca
 | `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:

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)

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

@@ -0,0 +1,106 @@
+---
+title: Console App Application Insights 2.x to 3.x Migration
+category: migration
+applies-to: 3.x
+---
+
+# Console App — AI SDK 2.x → 3.x Migration
+
+## What changed
+
+Console apps use `TelemetryConfiguration` directly (non-DI). In 3.x, the core SDK is rebuilt on OpenTelemetry internally. Several APIs on `TelemetryConfiguration` and `TelemetryClient` are removed or changed.
+
+Key changes:
+- `TelemetryConfiguration.Active` — **Removed**. Use `TelemetryConfiguration.CreateDefault()`. Returns a static singleton in 3.x.
+- `config.InstrumentationKey` — **Removed**. Use `config.ConnectionString` (required — throws if not set).
+- `config.TelemetryInitializers` collection — **Removed**. Use `config.ConfigureOpenTelemetryBuilder(b => b.WithTracing(t => t.AddProcessor<T>()))`.
+- `config.TelemetryProcessors` / `TelemetryProcessorChainBuilder` — **Removed**. Use OpenTelemetry processors.
+- `config.TelemetryChannel` / `TelemetrySinks` — **Removed**. Export pipeline managed by OpenTelemetry internally.
+- `DependencyTrackingTelemetryModule` manual init — **No longer needed**. Dependency tracking is automatic in 3.x.
+- `new TelemetryClient()` (parameterless) — **Removed**. Use `new TelemetryClient(config)`.
+- `SetAzureTokenCredential(object)` — Signature changed to `SetAzureTokenCredential(TokenCredential)` (strongly typed).
+
+## Before / after
+
+**2.x**
+```csharp
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.DependencyCollector;
+using Microsoft.ApplicationInsights.Extensibility;
+
+var config = TelemetryConfiguration.Active; // or CreateDefault()
+config.InstrumentationKey = "your-ikey";
+config.TelemetryInitializers.Add(new MyInitializer());
+
+var dtModule = new DependencyTrackingTelemetryModule();
+dtModule.Initialize(config);
+
+var client = new TelemetryClient(config);
+client.TrackEvent("Started");
+// ...
+client.Flush();
+```
+
+**3.x**
+```csharp
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.Extensibility;
+using OpenTelemetry;
+
+var config = TelemetryConfiguration.CreateDefault();
+config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+
+// Extensibility via OpenTelemetry builder
+config.ConfigureOpenTelemetryBuilder(builder =>
+{
+    builder.WithTracing(tracing => tracing.AddProcessor<MyActivityProcessor>());
+});
+
+var client = new TelemetryClient(config);
+client.TrackEvent("Started");
+// ...
+client.Flush();
+```
+
+## Removed APIs
+
+| API | Status | Replacement |
+|---|---|---|
+| `TelemetryConfiguration.Active` | **Removed** | `TelemetryConfiguration.CreateDefault()` (static singleton) |
+| `TelemetryConfiguration(string ikey)` | **Removed** | `CreateDefault()` + set `ConnectionString` |
+| `config.InstrumentationKey` | **Removed** | `config.ConnectionString` |
+| `config.TelemetryInitializers` | **Removed** | `config.ConfigureOpenTelemetryBuilder(...)` with `AddProcessor<T>()` |
+| `config.TelemetryProcessors` | **Removed** | `config.ConfigureOpenTelemetryBuilder(...)` with `AddProcessor<T>()` |
+| `config.TelemetryChannel` | **Removed** | Managed internally by OpenTelemetry |
+| `config.TelemetrySinks` | **Removed** | Use OpenTelemetry exporters via `ConfigureOpenTelemetryBuilder` |
+| `new TelemetryClient()` | **Removed** | `new TelemetryClient(config)` |
+| `client.InstrumentationKey` | **Removed** | Use `config.ConnectionString` |
+| `DependencyTrackingTelemetryModule` | **Not needed** | Dependency tracking is automatic |
+| `OperationCorrelationTelemetryInitializer` | **Not needed** | Correlation is automatic via OpenTelemetry |
+| `HttpDependenciesParsingTelemetryInitializer` | **Not needed** | Parsing is automatic |
+
+## New APIs
+
+| API | Description |
+|---|---|
+| `config.ConnectionString` | Required. Set before creating `TelemetryClient`. |
+| `config.ConfigureOpenTelemetryBuilder(Action<IOpenTelemetryBuilder>)` | Hook for adding processors, exporters, instrumentation. **Requires `using OpenTelemetry;`** — the `WithTracing()`, `WithLogging()`, `WithMetrics()`, and `ConfigureResource()` extension methods are in the root `OpenTelemetry` namespace. |
+| `config.SetAzureTokenCredential(TokenCredential)` | AAD auth (strongly typed — was `object` in 2.x) |
+| `config.SamplingRatio` | Fixed-rate sampling (0.0–1.0) |
+| `config.TracesPerSecond` | Rate-limited sampling |
+
+## Migration steps
+
+1. Replace `TelemetryConfiguration.Active` with `TelemetryConfiguration.CreateDefault()`
+2. Replace `config.InstrumentationKey = "..."` with `config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=..."`
+3. Remove manual `DependencyTrackingTelemetryModule` initialization — dependency tracking is automatic
+4. Remove `OperationCorrelationTelemetryInitializer` and `HttpDependenciesParsingTelemetryInitializer` — correlation and parsing are automatic
+5. Migrate custom `ITelemetryInitializer` implementations to `BaseProcessor<Activity>` — register via `config.ConfigureOpenTelemetryBuilder(b => b.WithTracing(t => t.AddProcessor<T>()))`
+6. Update `SetAzureTokenCredential((object)cred)` to `SetAzureTokenCredential(cred)` (remove cast — parameter is now `TokenCredential`)
+7. Update the NuGet package: `Microsoft.ApplicationInsights` to `3.*`, remove `Microsoft.ApplicationInsights.DependencyCollector`
+
+## See also
+
+- [TelemetryConfigurationBuilder API reference](learn://api-reference/dotnet/TelemetryConfigurationBuilder.md)
+- [TelemetryClient API reference](learn://api-reference/dotnet/TelemetryClient.md)
+- [AAD Authentication Migration](learn://migration/dotnet/aad-authentication-migration.md)

package/dist/Instrumentation/Resources/migration/dotnet/ilogger-migration.md

@@ -0,0 +1,54 @@
+---
+title: ILogger and Log Filtering Migration (2.x to 3.x)
+category: migration
+applies-to: 3.x
+---
+
+# ILogger and Log Filtering Migration (2.x → 3.x)
+
+## What changed
+
+In 2.x, `AddApplicationInsightsTelemetry()` already captured ILogger output automatically. However, some codebases also called `AddApplicationInsights()` on `ILoggingBuilder` explicitly — for example, to configure `ApplicationInsightsLoggerOptions` or to add category-level log filters targeting `ApplicationInsightsLoggerProvider`.
+
+In 3.x, ILogger capture remains automatic. The difference is that the underlying provider is now `OpenTelemetryLoggerProvider` (from the OpenTelemetry SDK). Any explicit `AddApplicationInsights()` calls and filters targeting `ApplicationInsightsLoggerProvider` must be updated.
+
+| Aspect | 2.x | 3.x |
+|---|---|---|
+| Logger provider | `ApplicationInsightsLoggerProvider` (explicit) | `OpenTelemetryLoggerProvider` (automatic) |
+| Registration | `loggingBuilder.AddApplicationInsights()` | Not needed — automatic |
+| Category filters | `AddFilter<ApplicationInsightsLoggerProvider>(...)` | `AddFilter<OpenTelemetryLoggerProvider>(...)` or plain `AddFilter(...)` |
+| Advanced filtering | `ITelemetryProcessor` | `BaseProcessor<LogRecord>` via `ConfigureOpenTelemetryLoggerProvider` |
+
+## Before / after
+
+**2.x**
+```csharp
+using Microsoft.Extensions.Logging.ApplicationInsights;
+
+builder.Services.AddLogging(loggingBuilder =>
+{
+    loggingBuilder.AddApplicationInsights(options =>
+    {
+        options.TrackExceptionsAsExceptionTelemetry = true;
+        options.IncludeScopes = true;
+    });
+    loggingBuilder.AddFilter<ApplicationInsightsLoggerProvider>("Microsoft.AspNetCore", LogLevel.Warning);
+    loggingBuilder.AddFilter<ApplicationInsightsLoggerProvider>("MyApp", LogLevel.Information);
+});
+```
+
+**3.x**
+```csharp
+using OpenTelemetry.Logs; // Required for OpenTelemetryLoggerProvider
+
+// Logging is automatic — just configure filters targeting the OTel provider
+builder.Logging.AddFilter<OpenTelemetryLoggerProvider>("Microsoft.AspNetCore", LogLevel.Warning);
+builder.Logging.AddFilter<OpenTelemetryLoggerProvider>("MyApp", LogLevel.Information);
+```
+
+## Migration steps
+
+1. **Remove `AddApplicationInsights()`** — delete the call and its options lambda (`TrackExceptionsAsExceptionTelemetry`, `IncludeScopes` no longer exist).
+2. **Replace log filters** — change `AddFilter<ApplicationInsightsLoggerProvider>` to `AddFilter<OpenTelemetryLoggerProvider>`, or use a plain `AddFilter(category, level)`. Add `using OpenTelemetry.Logs;` if targeting the provider specifically.
+3. **Update usings** — remove `using Microsoft.Extensions.Logging.ApplicationInsights;`.
+4. **Remove the package** — `Microsoft.Extensions.Logging.ApplicationInsights` is no longer needed.

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

@@ -0,0 +1,126 @@
+---
+title: WorkerService 2.x to 3.x Code Migration
+category: migration
+applies-to: 3.x
+---
+
+# Worker Service 2.x → 3.x Code Migration
+
+## What changed
+
+3.x uses OpenTelemetry under the hood. The main entry point is the same — `AddApplicationInsightsTelemetryWorkerService()` — but several options and an extension method were removed.
+
+Key changes:
+- `InstrumentationKey` → use `ConnectionString`
+- `EnableAdaptiveSampling` → use `TracesPerSecond` (default `5`) or `SamplingRatio`
+- Logging is automatic — no additional logger provider needed
+- New: `Credential` for AAD authentication, `EnableTraceBasedLogsSampler` for log sampling control
+
+## Before / after
+
+**2.x**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+builder.ConfigureServices(services =>
+{
+    services.AddApplicationInsightsTelemetryWorkerService(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.WorkerService;
+
+builder.ConfigureServices(services =>
+{
+    services.AddApplicationInsightsTelemetryWorkerService(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 `AddApplicationInsightsTelemetryWorkerService()` 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`. |
+| `AddAutoCollectedMetricExtractor` | Unchanged | None. Default `true`. |
+| `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. |
+| `EnableDebugLogger` | **Removed** | Delete the line. |
+| `DependencyCollectionOptions` | **Removed** | Delete the line. |
+| `EnableEventCounterCollectionModule` | **Removed** | Delete the line. |
+| `EnableAppServicesHeartbeatTelemetryModule` | **Removed** | Delete the line; heartbeat is automatic. |
+| `EnableAzureInstanceMetadataTelemetryModule` | **Removed** | Delete the line; resource detection is automatic. |
+| `EnableDiagnosticsTelemetryModule` | **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 |
+|---|---|
+| `AddApplicationInsightsTelemetryWorkerService(string instrumentationKey)` | Use parameterless overload + `ConnectionString` in options or env var. |
+
+## 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. |
+
+## Migration steps
+
+1. Update the package:
+   ```xml
+   <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" 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`, `DependencyCollectionOptions`, `EnableEventCounterCollectionModule`, `EnableAppServicesHeartbeatTelemetryModule`, `EnableAzureInstanceMetadataTelemetryModule`, or `EnableDiagnosticsTelemetryModule`
+   - Replace `AddApplicationInsightsTelemetryWorkerService("your-ikey")` with `AddApplicationInsightsTelemetryWorkerService()` and set `ConnectionString` via options or env var
+
+3. Migrate TelemetryClient breaking calls:
+   - 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 workerservice-2x-to-3x-no-code-change.md)
+- AddApplicationInsightsTelemetryWorkerService API reference(see in AddApplicationInsightsTelemetryWorkerService.md)
+- TelemetryClient breaking changes(see in TelemetryClient.md)