[Extensions.Enrichment] Rename some AddTraceEnricher methods to TryAddTraceEnricher

examples/enrichment/Examples.Enrichment/Program.cs

@@ -25,8 +25,8 @@ public static void Main()
             .AddSource("MyCompany.MyProduct.MyLibrary")
 
             // Register an enricher class.
-            // Important: AddTraceEnricher() must be called before any exporters.
-            .AddTraceEnricher<MyTraceEnricher>()
+            // Important: TryAddTraceEnricher() must be called before any exporters.
+            .TryAddTraceEnricher<MyTraceEnricher>()
 
             // Add Console exporter to see the output of this example.
             .AddConsoleExporter()

src/OpenTelemetry.Extensions.Enrichment/.publicApi/PublicAPI.Unshipped.txt

@@ -7,12 +7,12 @@ OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag.Add(string! key, object?
 OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag.TraceEnrichmentBag() -> void
 OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag.TraceEnrichmentBag(System.Diagnostics.Activity! activity) -> void
 OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions
-static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.AddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, OpenTelemetry.Extensions.Enrichment.TraceEnricher! enricher) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
+static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.TryAddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, OpenTelemetry.Extensions.Enrichment.TraceEnricher! enricher) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.AddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action<OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag>! enrichmentAction) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.AddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Func<System.IServiceProvider!, OpenTelemetry.Extensions.Enrichment.TraceEnricher!>! enricherImplementationFactory) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
-static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.AddTraceEnricher<T>(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
-static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.AddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder, OpenTelemetry.Extensions.Enrichment.TraceEnricher! enricher) -> OpenTelemetry.Trace.TracerProviderBuilder!
+static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.TryAddTraceEnricher<T>(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
+static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.TryAddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder, OpenTelemetry.Extensions.Enrichment.TraceEnricher! enricher) -> OpenTelemetry.Trace.TracerProviderBuilder!
 static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.AddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder, System.Action<OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag>! enrichmentAction) -> OpenTelemetry.Trace.TracerProviderBuilder!
 static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.AddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder, System.Func<System.IServiceProvider!, OpenTelemetry.Extensions.Enrichment.TraceEnricher!>! enricherImplementationFactory) -> OpenTelemetry.Trace.TracerProviderBuilder!
-static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.AddTraceEnricher<T>(this OpenTelemetry.Trace.TracerProviderBuilder! builder) -> OpenTelemetry.Trace.TracerProviderBuilder!
+static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.TryAddTraceEnricher<T>(this OpenTelemetry.Trace.TracerProviderBuilder! builder) -> OpenTelemetry.Trace.TracerProviderBuilder!
 virtual OpenTelemetry.Extensions.Enrichment.TraceEnricher.EnrichOnActivityStart(in OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag bag) -> void

src/OpenTelemetry.Extensions.Enrichment/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+* Renamed some extension methods from `AddTraceEnricher*()` to
+`TryAddTraceEnricer*()` pattern to more accurately reflect their behavior of
+only adding the enricher if it hasn't already been added.
+([#3085](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/pull/3085))
+
 ## 1.12.0-alpha.1
 
 Released 2025-Aug-18

src/OpenTelemetry.Extensions.Enrichment/OpenTelemetry.Extensions.Enrichment.csproj

@@ -21,7 +21,6 @@
 
   <ItemGroup>
     <Compile Include="$(RepoRoot)\src\Shared\Guard.cs" Link="Includes\Guard.cs" />
-    <Compile Include="$(RepoRoot)\src\Shared\IsExternalInit.cs" Link="Includes\IsExternalInit.cs" />
   </ItemGroup>
 
 </Project>

src/OpenTelemetry.Extensions.Enrichment/README.md

@@ -79,15 +79,15 @@ in your application.
 ### Step 3: Register enricher class
 
 Add your custom enricher class to the `TracerProviderBuilder` by calling the
-`AddTraceEnricher<T>()` method. Configure other services via
+`TryAddTraceEnricher<T>()` method. Configure other services via
 `ConfigureServices()`, add `ActivitySource` and an exporter as usual:
 
 ```csharp
 using var MyActivitySource = new ActivitySource("MyCompany.MyProduct.MyLibrary");
 using var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .ConfigureServices(services => services.AddSingleton<IMyService, MyService>())
     .AddSource("MyCompany.MyProduct.MyLibrary")
-    .AddTraceEnricher<MyTraceEnricher>()
+    .TryAddTraceEnricher<MyTraceEnricher>()
     .AddConsoleExporter()
     .Build();
 ```
@@ -103,7 +103,7 @@ public void ConfigureServices(IServiceCollection services)
     services.AddSingleton<IMyService, MyService>();
     services.AddOpenTelemetry().WithTracing((builder) => builder
         .AddSource("MyCompany.MyProduct.MyLibrary")
-        .AddTraceEnricher<MyTraceEnricher>()
+        .TryAddTraceEnricher<MyTraceEnricher>()
         .AddConsoleExporter());
 }
 ```
@@ -155,16 +155,16 @@ enricher class. In this case, the enricher class will be created for you by
 Dependency Injection:
 
 ```csharp
-public static AddTraceEnricher<T>(this IServiceCollection services)
-public static AddTraceEnricher<T>(this TracerProviderBuilder builder)
+public static TryAddTraceEnricher<T>(this IServiceCollection services)
+public static TryAddTraceEnricher<T>(this TracerProviderBuilder builder)
 ```
 
 If you prefer to instantiate your enricher class on your own, you may use one of
 these methods which allow for the usage of pre-existing enricher objects:
 
 ```csharp
-public static AddTraceEnricher(this IServiceCollection services, TraceEnricher enricher)
-public static AddTraceEnricher(this TracerProviderBuilder builder, TraceEnricher enricher)
+public static TryAddTraceEnricher(this IServiceCollection services, TraceEnricher enricher)
+public static TryAddTraceEnricher(this TracerProviderBuilder builder, TraceEnricher enricher)
 ```
 
 If you only need to enrich a small amount of data, it may not be necessary to create

src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentProviderBuilderExtensions.cs

@@ -16,7 +16,7 @@ namespace OpenTelemetry.Extensions.Enrichment;
 public static class TraceEnrichmentProviderBuilderExtensions
 {
     /// <summary>
-    /// Adds trace enricher.
+    /// Adds a <see cref="TraceEnricher"/> implementation of type <typeparamref name="T"/> as a Singleton to the specified <see cref="TracerProviderBuilder"/> if one has not already been registered.
     /// </summary>
     /// <param name="builder"><see cref="TracerProviderBuilder"/> being configured.</param>
     /// <typeparam name="T">Enricher object type.</typeparam>
@@ -26,20 +26,20 @@ public static class TraceEnrichmentProviderBuilderExtensions
     /// Add this enricher *before* exporter related Activity processors.
     /// </remarks>
 #if NET
-    public static TracerProviderBuilder AddTraceEnricher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>(this TracerProviderBuilder builder)
+    public static TracerProviderBuilder TryAddTraceEnricher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>(this TracerProviderBuilder builder)
 #else
-    public static TracerProviderBuilder AddTraceEnricher<T>(this TracerProviderBuilder builder)
+    public static TracerProviderBuilder TryAddTraceEnricher<T>(this TracerProviderBuilder builder)
 #endif
         where T : TraceEnricher
     {
         Guard.ThrowIfNull(builder);
 
         return builder
-            .ConfigureServices(services => services.AddTraceEnricher<T>());
+            .ConfigureServices(services => services.TryAddTraceEnricher<T>());
     }
 
     /// <summary>
-    /// Adds trace enricher.
+    /// Adds a <see cref="TraceEnricher"/> implementation of type <paramref name="enricher"/> as a Singleton to the specified <see cref="TracerProviderBuilder"/> if one has not already been registered.
     /// </summary>
     /// <param name="builder"><see cref="TracerProviderBuilder"/> being configured.</param>
     /// <param name="enricher">The <see cref="TraceEnricher"/> object being added.</param>
@@ -48,17 +48,17 @@ public static TracerProviderBuilder AddTraceEnricher<T>(this TracerProviderBuild
     /// <remarks>
     /// Add this enricher *before* exporter related Activity processors.
     /// </remarks>
-    public static TracerProviderBuilder AddTraceEnricher(this TracerProviderBuilder builder, TraceEnricher enricher)
+    public static TracerProviderBuilder TryAddTraceEnricher(this TracerProviderBuilder builder, TraceEnricher enricher)
     {
         Guard.ThrowIfNull(builder);
         Guard.ThrowIfNull(enricher);
 
         return builder
-            .ConfigureServices(services => services.AddTraceEnricher(enricher));
+            .ConfigureServices(services => services.TryAddTraceEnricher(enricher));
     }
 
     /// <summary>
-    /// Adds trace enricher.
+    /// Adds a trace enricher delegate to the specified <see cref="TracerProviderBuilder"/>.
     /// </summary>
     /// <param name="builder"><see cref="TracerProviderBuilder"/> being configured.</param>
     /// <param name="enrichmentAction">The <see cref="TraceEnrichmentBag"/> delegate to enrich traces.</param>
@@ -77,7 +77,7 @@ public static TracerProviderBuilder AddTraceEnricher(this TracerProviderBuilder
     }
 
     /// <summary>
-    /// Adds trace enricher.
+    /// Adds a trace enricher factory to the specified <see cref="TracerProviderBuilder"/>.
     /// </summary>
     /// <param name="builder"><see cref="TracerProviderBuilder"/> being configured.</param>
     /// <param name="enricherImplementationFactory">The <see cref="TraceEnricher"/> object being added using implementation factory.</param>

src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentServiceCollectionExtensions.cs

@@ -17,7 +17,7 @@ namespace Microsoft.Extensions.DependencyInjection;
 public static class TraceEnrichmentServiceCollectionExtensions
 {
     /// <summary>
-    /// Adds trace enricher.
+    /// Adds a <see cref="TraceEnricher"/> implementation of type <typeparamref name="T"/> as a Singleton to the specified <see cref="IServiceCollection"/> if one has not already been registered.
     /// </summary>
     /// <param name="services"><see cref="IServiceCollection"/> being configured.</param>
     /// <typeparam name="T">Enricher object type.</typeparam>
@@ -27,21 +27,21 @@ public static class TraceEnrichmentServiceCollectionExtensions
     /// Add this enricher *before* exporter related Activity processors.
     /// </remarks>
 #if NET
-    public static IServiceCollection AddTraceEnricher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>(this IServiceCollection services)
+    public static IServiceCollection TryAddTraceEnricher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>(this IServiceCollection services)
 #else
-    public static IServiceCollection AddTraceEnricher<T>(this IServiceCollection services)
+    public static IServiceCollection TryAddTraceEnricher<T>(this IServiceCollection services)
 #endif
         where T : TraceEnricher
     {
         Guard.ThrowIfNull(services);
 
-        return services
-            .TryAddEnrichment()
-            .AddSingleton<TraceEnricher, T>();
+        services.TryAddEnumerable(ServiceDescriptor.Singleton<TraceEnricher, T>());
+
+        return services.TryAddEnrichment();
     }
 
     /// <summary>
-    /// Adds trace enricher.
+    /// Adds a <see cref="TraceEnricher"/> implementation of type <paramref name="enricher"/> as a Singleton to the specified <see cref="IServiceCollection"/> if one has not already been registered.
     /// </summary>
     /// <param name="services"><see cref="IServiceCollection"/> being configured.</param>
     /// <param name="enricher">The <see cref="TraceEnricher"/> object being added.</param>
@@ -50,18 +50,18 @@ public static IServiceCollection AddTraceEnricher<T>(this IServiceCollection ser
     /// <remarks>
     /// Add this enricher *before* exporter related Activity processors.
     /// </remarks>
-    public static IServiceCollection AddTraceEnricher(this IServiceCollection services, TraceEnricher enricher)
+    public static IServiceCollection TryAddTraceEnricher(this IServiceCollection services, TraceEnricher enricher)
     {
         Guard.ThrowIfNull(services);
         Guard.ThrowIfNull(enricher);
 
-        return services
-            .TryAddEnrichment()
-            .AddSingleton(enricher);
+        services.TryAddEnumerable(ServiceDescriptor.Singleton(enricher));
+
+        return services.TryAddEnrichment();
     }
 
     /// <summary>
-    /// Adds trace enricher.
+    /// Adds a trace enricher delegate to the specified <see cref="IServiceCollection"/>.
     /// </summary>
     /// <param name="services"><see cref="IServiceCollection"/> being configured.</param>
     /// <param name="enrichmentAction">The <see cref="TraceEnrichmentBag"/> delegate to enrich traces.</param>
@@ -83,7 +83,7 @@ public static IServiceCollection AddTraceEnricher(this IServiceCollection servic
     }
 
     /// <summary>
-    /// Adds trace enricher.
+    /// Adds a trace enricher factory to the specified <see cref="IServiceCollection"/>.
     /// </summary>
     /// <param name="services"><see cref="IServiceCollection"/> being configured.</param>
     /// <param name="enricherImplementationFactory">The <see cref="TraceEnricher"/> object being added using implementation factory.</param>
@@ -99,7 +99,7 @@ public static IServiceCollection AddTraceEnricher(this IServiceCollection servic
 
         return services
             .TryAddEnrichment()
-            .AddSingleton((serviceProvider) => enricherImplementationFactory(serviceProvider));
+            .AddSingleton(enricherImplementationFactory);
     }
 
     private static IServiceCollection TryAddEnrichment(this IServiceCollection services)

test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentProviderBuilderExtensions.cs

@@ -12,14 +12,14 @@ public sealed class OpenTelemetryEnrichmentProviderBuilderExtensions
     private const string SourceName = nameof(OpenTelemetryEnrichmentProviderBuilderExtensions);
 
     [Fact]
-    public void AddTraceEnricherOfTRegistersEnricher()
+    public void GenericMethod_RegistersEnricher()
     {
         var exportedItems = new List<Activity>();
 
         using var tracerProvider = Sdk.CreateTracerProviderBuilder()
             .AddSource(SourceName)
-            .AddTraceEnricher<MyTraceEnricher>()
-            .AddTraceEnricher<MyTraceEnricher2>()
+            .TryAddTraceEnricher<MyTraceEnricher>()
+            .TryAddTraceEnricher<MyTraceEnricher2>()
             .AddInMemoryExporter(exportedItems)
             .Build();
 
@@ -41,14 +41,14 @@ public void AddTraceEnricherOfTRegistersEnricher()
     }
 
     [Fact]
-    public void AddTraceEnricherRegistersEnricher()
+    public void InstanceMethod_RegistersEnricher()
     {
         var exportedItems = new List<Activity>();
 
         using var tracerProvider = Sdk.CreateTracerProviderBuilder()
             .AddSource(SourceName)
-            .AddTraceEnricher(new MyTraceEnricher())
-            .AddTraceEnricher(new MyTraceEnricher2())
+            .TryAddTraceEnricher(new MyTraceEnricher())
+            .TryAddTraceEnricher(new MyTraceEnricher2())
             .AddInMemoryExporter(exportedItems)
             .Build();
 
@@ -71,7 +71,7 @@ public void AddTraceEnricherRegistersEnricher()
     }
 
     [Fact]
-    public void AddTraceEnricherActionRegistersEnricher()
+    public void DelegateMethod_RegistersEnricher()
     {
         var exportedItems = new List<Activity>();
 
@@ -106,7 +106,7 @@ public void AddTraceEnricherActionRegistersEnricher()
     }
 
     [Fact]
-    public void AddTraceEnricherFactoryRegistersEnricher()
+    public void FactoryMethod_RegistersEnricher()
     {
         var exportedItems = new List<Activity>();
 

test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentServiceCollectionExtensionsTests.cs

@@ -14,7 +14,7 @@ public sealed class OpenTelemetryEnrichmentServiceCollectionExtensionsTests
     private const string SourceName = nameof(OpenTelemetryEnrichmentServiceCollectionExtensionsTests);
 
     [Fact]
-    public async Task AddTraceEnricherOfTRegistersEnricher()
+    public async Task GenericMethod_TRegistersEnricher()
     {
         var exportedItems = new List<Activity>();
 
@@ -25,8 +25,8 @@ public async Task AddTraceEnricherOfTRegistersEnricher()
                     .AddSource(SourceName)
                     .AddInMemoryExporter(exportedItems))
                 .Services
-                .AddTraceEnricher<MyTraceEnricher>()
-                .AddTraceEnricher<MyTraceEnricher2>())
+                .TryAddTraceEnricher<MyTraceEnricher>()
+                .TryAddTraceEnricher<MyTraceEnricher2>())
             .Build();
 
         await host.StartAsync();
@@ -62,7 +62,7 @@ public async Task AddTraceEnricherOfTRegistersEnricher()
     }
 
     [Fact]
-    public async Task AddTraceEnricherRegistersEnricher()
+    public async Task InstanceMethod_RegistersEnricher()
     {
         var exportedItems = new List<Activity>();
 
@@ -73,8 +73,8 @@ public async Task AddTraceEnricherRegistersEnricher()
                     .AddSource(SourceName)
                     .AddInMemoryExporter(exportedItems))
                 .Services
-                .AddTraceEnricher(new MyTraceEnricher())
-                .AddTraceEnricher(new MyTraceEnricher2()))
+                .TryAddTraceEnricher(new MyTraceEnricher())
+                .TryAddTraceEnricher(new MyTraceEnricher2()))
             .Build();
 
         await host.StartAsync();
@@ -103,7 +103,7 @@ public async Task AddTraceEnricherRegistersEnricher()
     }
 
     [Fact]
-    public async Task AddTraceEnricherActionRegistersEnricher()
+    public async Task DelegateMethod_RegistersEnricher()
     {
         var exportedItems = new List<Activity>();
 
@@ -144,7 +144,7 @@ public async Task AddTraceEnricherActionRegistersEnricher()
     }
 
     [Fact]
-    public async Task AddTraceEnricherFactoryRegistersEnricher()
+    public async Task FactoryMethod_RegistersEnricher()
     {
         var exportedItems = new List<Activity>();