Fix #3163: per-call TelemetryContext enrichment in Track*/StartOperation*

[rajkumar-rangaraj]

Summary

Fixes #3163 — constructing a second TelemetryClient against a TelemetryConfiguration that has already been built (e.g. by the ASP.NET classic ApplicationInsightsHttpModule or by a prior TelemetryClient instantiation) no longer throws InvalidOperationException: "Configuration cannot be modified after it has been built."

It also fixes the related correctness issue introduced in 3.1.0 (#3137) where the first TelemetryClients Context leaked to every subsequent client because it was registered globally as an OTel pipeline processor.

Root cause

Prior to this PR, the non-DI TelemetryClient constructor called configuration.PrependOpenTelemetryBuilderConfiguration(...) to register TelemetryContextActivityProcessor and TelemetryContextLogProcessor every time it ran. After the first Build() the configuration is sealed, so the second constructor call threw. Even when that issue was worked around, every subsequent TelemetryClient would be silently shadowed by the first clients Context because the processors were keyed to the first clients TelemetryContext instance.

Approach (Path A — source-level per-call enrichment)

Move TelemetryContext enrichment from a pipeline-wide processor to the call site of every Track*/StartOperation* method on TelemetryClient. This is the architecturally clean fix:

• Each TelemetryClient carries its own Context. At every Track*/StartOperation* invocation, the clients Context (typed fields + GlobalProperties) is applied to the outgoing properties dict or Activity tags with skip-if-present semantics, so item-level values continue to take precedence.
• The non-DI constructor now just calls the idempotent configuration.Build(). No pipeline mutation. Constructing N additional TelemetryClient instances against the same configuration is safe and cheap.
• Precedence at the emission site is item dict > GlobalProperties > typed Context, matching the existing behavior expected by TelemetryClientTests.
• The DI path (UseApplicationInsightsTelemetry for ASP.NET Core / Worker Service) is unchanged — it still registers pipeline-wide TelemetryContextActivityProcessor/TelemetryContextLogProcessor so OTel-native signals (ActivitySource, ILogger) emitted outside a TelemetryClient.Track* call continue to be enriched.

Changes

BASE/src/Microsoft.ApplicationInsights/TelemetryClient.cs

• Non-DI constructor no longer calls PrependOpenTelemetryBuilderConfiguration; it just calls Build() (idempotent, thread-safe).
• New static helpers:
  • BuildClientContextProperties(TelemetryContext, IDictionary<string,string>) — returns a mutable, client-context-enriched properties dict (used by Track* overloads that dont take an item-level telemetry object).
  • EnrichActivityWithClientContext(TelemetryContext, Activity) — applies client context to an activity (used by StartOperation).
• Refactored ApplyContextToProperties / ApplyContextToActivity to take an overwrite flag. When overwrite=false they implement skip-if-present (preserving caller-set keys/tags).
• All 10 Track* methods and all 3 StartOperation overloads now thread the clients Context through.

BASE/src/Microsoft.ApplicationInsights/TelemetryClientExtensions.cs

• All 3 StartOperation overloads enrich the freshly-started Activity with telemetryClient.Context via EnrichActivityWithClientContext.

WEB/Src/Web/Web/ApplicationInsightsHttpModule.cs

• Added static TelemetryClient sharedTelemetryClient (one host-blessed client per AppDomain).
• Creation is lazy on first OnBeginRequest so Init() no longer triggers Build() (which can fail when no connection string is configured).
• Dispose is unchanged (the shared instance lives until the AppDomain unloads).

Tests

• New BASE/Test/.../TelemetryClientMultiInstanceTests.cs (6 tests):
  • SecondTelemetryClient_AgainstBuiltConfiguration_DoesNotThrow — direct InvalidOperationException from Microsoft.ApplicationInsights 3.1.0 Packages in ASP.Net 4.8 #3163 regression.
  • ParallelTelemetryClientConstruction_DoesNotThrow — 32 parallel ctors.
  • EachTelemetryClient_HasIsolatedContext — verifies per-instance Context isolation.
  • TrackTrace_FromDifferentClients_CarriesEachClientsContext — verifies log path enrichment is per-client.
  • ItemLevelContext_TakesPrecedenceOverClientContext — verifies skip-if-present precedence.
  • TrackDependency_FromDifferentClients_CarriesEachClientsContext — verifies activity path enrichment is per-client.
• New tests in WEB/Src/Web/Web.Tests/ApplicationInsightsHttpModuleTests.cs (2):
  • Init_AllowsAdditionalTelemetryClientsToBeConstructedAfterInit — InvalidOperationException from Microsoft.ApplicationInsights 3.1.0 Packages in ASP.Net 4.8 #3163 regression in the HttpModule scenario.
  • Init_AdditionalTelemetryClients_HaveIsolatedContext — per-client Context isolation in the same scenario.

Test results

• BASE (Microsoft.ApplicationInsights.Tests, net8.0): 225/225 pass — including the 6 new tests.
• WEB HttpModule (net462): 16/16 pass — including the 2 new tests.
• NETCORE Integration (net8.0): 39/39 pass — confirming the DI path is unchanged.

Diff stat

 BASE/src/Microsoft.ApplicationInsights/TelemetryClient.cs           | 297 +++++++++++++--------
 BASE/src/Microsoft.ApplicationInsights/TelemetryClientExtensions.cs |  12 +
 WEB/Src/Web/Web/ApplicationInsightsHttpModule.cs                    |  23 +-
 WEB/Src/Web/Web.Tests/ApplicationInsightsHttpModuleTests.cs         |  73 +++++
 BASE/Test/.../TelemetryClientMultiInstanceTests.cs                  | new
 CHANGELOG.md                                                        |   1 +
 6 files changed, 499 insertions(+), 115 deletions(-)

Backward compatibility

• Public API: no changes (no edits to .publicApi/PublicAPI.Unshipped.txt).
• DI scenarios (ASP.NET Core, Worker Service): unchanged behavior; pipeline-wide context processors remain.
• Non-DI scenarios (classic ASP.NET, console, NLog): now per-client Context is correctly scoped to that client. The only observable difference for non-DI users is that raw ActivitySource.StartActivity(...) / ILogger.Log(...) calls (not routed through TelemetryClient) no longer get auto-enriched with the first TelemetryClients Context. This was an undocumented side effect of the 3.1.0 design; restoring v3.0.0 behavior is arguably correct.

CHANGELOG

Added an Unreleased entry. The placeholder /pull/0000 URL will be replaced with the real PR number after this PR is opened.

Closes #3163.

[Copilot]

Pull request overview

This PR fixes multi-TelemetryClient construction against an already-built TelemetryConfiguration (classic ASP.NET HttpModule + other non-DI scenarios) by removing per-constructor OpenTelemetry pipeline mutations and moving TelemetryClient.Context enrichment to the call sites of Track* / StartOperation*, ensuring per-client Context isolation.

Changes:

• Refactors TelemetryClient to apply client context per call (properties + Activity tags) instead of registering global OTel processors in the non-DI ctor.
• Updates classic ASP.NET ApplicationInsightsHttpModule to lazily create a single AppDomain-shared TelemetryClient on first request.
• Adds regression/unit tests for multi-instance construction and per-client context isolation; updates changelog.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
BASE/src/Microsoft.ApplicationInsights/TelemetryClient.cs	Removes non-DI pipeline mutation; adds per-call context enrichment helpers and threads client context through Track*/StartOperation paths.
BASE/src/Microsoft.ApplicationInsights/TelemetryClientExtensions.cs	Enriches freshly started activities with the calling client’s context.
WEB/Src/Web/Web/ApplicationInsightsHttpModule.cs	Switches to a lazily-created AppDomain-shared TelemetryClient on first request.
WEB/Src/Web/Web.Tests/ApplicationInsightsHttpModuleTests.cs	Adds regressions for #3163 + context isolation; resets new static shared client between tests.
BASE/Test/.../TelemetryClientMultiInstanceTests.cs	Adds multi-instance constructor + context isolation regressions across log/activity export paths.
CHANGELOG.md	Adds Unreleased entry describing #3163 fix and behavior change rationale.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[harsimar]

CreateDefault() doesn't crash anymore, however if one tries to create a telemetryclient from the telemetry config in global.asax, you get another crash that looks like this:

 Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.                             
                                                                                                                                                                                                                                    
  Exception Details: System.InvalidOperationException: Configuration cannot be modified after it has been built. Create a new TelemetryConfiguration instance if you need different settings.                                       
                                                                                                                                                                                                                                    
  Source Error:                                                                                                                                                                                                                     
                                                                                                                                                                                                                                    
                                                                                                                                                                                                                                    
  Line 507:                    "Create a new TelemetryConfiguration instance if you need different settings.");                                                                                                                     
  Line 508:            }                                                                                                                                                                                                            
  Line 509:        }                                                                                                                                                                                                                
  Line 510:                                                                                                                                                                                                                         
  Line 511:        /// <summary>                                                                                                                                                                                                    
                                                                                                                                                                                                                                    
  Source File: C:\repos\ApplicationInsights-dotnet\BASE\src\Microsoft.ApplicationInsights\Extensibility\TelemetryConfiguration.cs    Line: 509                                                                                      
                                                                                                                                                                                                                                    
  Stack Trace:                                                                                                                                                                                                                      
                                                                                                                                                                                                                                    
                                                                                                                                                                                                                                    
  [InvalidOperationException: Configuration cannot be modified after it has been built. Create a new TelemetryConfiguration instance if you need different settings.]                                                               
     Microsoft.ApplicationInsights.Extensibility.TelemetryConfiguration.ThrowIfBuilt() in C:\repos\ApplicationInsights-dotnet\BASE\src\Microsoft.ApplicationInsights\Extensibility\TelemetryConfiguration.cs:509                    
     Microsoft.ApplicationInsights.Extensibility.TelemetryConfiguration.set_ExtensionVersion(String value) in C:\repos\ApplicationInsights-dotnet\BASE\src\Microsoft.ApplicationInsights\Extensibility\TelemetryConfiguration.cs:222
     Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule.Init(HttpApplication context) in C:\repos\ApplicationInsights-dotnet\WEB\Src\Web\Web\ApplicationInsightsHttpModule.cs:63                                       
     System.Web.HttpApplication.RegisterEventSubscriptionsWithIIS(IntPtr appContext, HttpContext context, MethodInfo[] handlers) +590                                                                                               
     System.Web.HttpApplication.InitSpecial(HttpApplicationState state, MethodInfo[] handlers, IntPtr appContext, HttpContext context) +168                                                                                         
     System.Web.HttpApplicationFactory.GetSpecialApplicationInstance(IntPtr appContext, HttpContext context) +277                                                                                                                   
     System.Web.Hosting.PipelineRuntime.InitializeApplication(IntPtr appContext) +369                                                                                                                                               
                                                                                                                                                                                                                                    
  [HttpException (0x80004005): Configuration cannot be modified after it has been built. Create a new TelemetryConfiguration instance if you need different settings.]                                                              
     System.Web.HttpRuntime.FirstRequestInit(HttpContext context) +532                                                                                                                                                              
     System.Web.HttpRuntime.EnsureFirstRequestInit(HttpContext context) +111                                                                                                                                                        
     System.Web.HttpRuntime.ProcessRequestNotificationPrivate(IIS7WorkerRequest wr, HttpContext context) +731 

Copilot suggesting below fix:

Read ApplicationInsightsHttpModule.cs
  │ WEB\Src\Web\Web\ApplicationInsightsHttpModule.cs
  └ L56:70 (15 lines read)

● The fix is a one-line change on line 61:

   // Before (uses process-wide singleton — crashes if already built):
   sharedTelemetryConfiguration = TelemetryConfiguration.CreateDefault();
   
   // After (private instance — always mutable):
   sharedTelemetryConfiguration = new TelemetryConfiguration();