Feature/modular bootstrapper

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Data/InventoryDbContext.cs

@@ -0,0 +1,18 @@
+using Examples.Bootstrapping.MultiModule.Domain.Inventory;
+using Microsoft.EntityFrameworkCore;
+using RCommon.Persistence.EFCore;
+
+namespace Examples.Bootstrapping.MultiModule.Data;
+
+/// <summary>
+/// DbContext for the Inventory module. A separate type from <see cref="OrderingDbContext"/> so that
+/// both can coexist under distinct data-store names without conflicting.
+/// </summary>
+public class InventoryDbContext : RCommonDbContext
+{
+    public InventoryDbContext(DbContextOptions<InventoryDbContext> options) : base(options)
+    {
+    }
+
+    public DbSet<InventoryItem> Items => Set<InventoryItem>();
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Data/OrderingDbContext.cs

@@ -0,0 +1,18 @@
+using Examples.Bootstrapping.MultiModule.Domain.Orders;
+using Microsoft.EntityFrameworkCore;
+using RCommon.Persistence.EFCore;
+
+namespace Examples.Bootstrapping.MultiModule.Data;
+
+/// <summary>
+/// DbContext for the Ordering module. Inherits directly from <see cref="RCommonDbContext"/> so that
+/// <c>DataStoreFactoryOptions.Register&lt;RCommonDbContext, OrderingDbContext&gt;("Ordering")</c> wires up correctly.
+/// </summary>
+public class OrderingDbContext : RCommonDbContext
+{
+    public OrderingDbContext(DbContextOptions<OrderingDbContext> options) : base(options)
+    {
+    }
+
+    public DbSet<Order> Orders => Set<Order>();
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Domain/Inventory/InventoryItem.cs

@@ -0,0 +1,13 @@
+namespace Examples.Bootstrapping.MultiModule.Domain.Inventory;
+
+/// <summary>
+/// Minimal InventoryItem aggregate used by the Inventory module.
+/// </summary>
+public class InventoryItem
+{
+    public Guid Id { get; set; }
+
+    public string Sku { get; set; } = string.Empty;
+
+    public int Quantity { get; set; }
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Domain/Orders/Order.cs

@@ -0,0 +1,12 @@
+namespace Examples.Bootstrapping.MultiModule.Domain.Orders;
+
+/// <summary>
+/// Minimal Order aggregate used by the Ordering module. Persistence configuration is
+/// intentionally lightweight; the example focuses on bootstrapping semantics, not domain depth.
+/// </summary>
+public class Order
+{
+    public Guid Id { get; set; }
+
+    public string CustomerName { get; set; } = string.Empty;
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Examples.Bootstrapping.MultiModule.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\Src\RCommon.Core\RCommon.Core.csproj" />
+    <ProjectReference Include="..\..\..\Src\RCommon.Persistence\RCommon.Persistence.csproj" />
+    <ProjectReference Include="..\..\..\Src\RCommon.EfCore\RCommon.EFCore.csproj" />
+    <ProjectReference Include="..\..\..\Src\RCommon.Caching\RCommon.Caching.csproj" />
+    <ProjectReference Include="..\..\..\Src\RCommon.MemoryCache\RCommon.MemoryCache.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- Matches the EF Core 10.0.2 versions pinned in Src/RCommon.EfCore for net10.0. -->
+    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.2" />
+  </ItemGroup>
+
+</Project>

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Modules/IServiceModule.cs

@@ -0,0 +1,13 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Examples.Bootstrapping.MultiModule.Modules;
+
+/// <summary>
+/// Minimal contract a module implements to configure services in a multi-module composition.
+/// Each module independently calls <c>services.AddRCommon()</c>; the bootstrapper guarantees
+/// idempotent and merge-able registration semantics across modules.
+/// </summary>
+public interface IServiceModule
+{
+    void Configure(IServiceCollection services);
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Modules/InventoryModule.cs

@@ -0,0 +1,26 @@
+using Examples.Bootstrapping.MultiModule.Data;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.DependencyInjection;
+using RCommon;
+using RCommon.Caching;
+using RCommon.MemoryCache;
+
+namespace Examples.Bootstrapping.MultiModule.Modules;
+
+/// <summary>
+/// The Inventory module configures its own DbContext under a distinct data-store name,
+/// re-declares the same guid generator (idempotent no-op), and adds in-memory caching.
+/// </summary>
+public class InventoryModule : IServiceModule
+{
+    public void Configure(IServiceCollection services)
+    {
+        services.AddRCommon()
+            .WithSimpleGuidGenerator() // Same impl as Ordering -> idempotent no-op.
+            .WithPersistence<EFCorePerisistenceBuilder>(ef =>
+                ef.AddDbContext<InventoryDbContext>(
+                    "Inventory",
+                    o => o.UseInMemoryDatabase("inventory")))
+            .WithMemoryCaching<InMemoryCachingBuilder>();
+    }
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Modules/NotificationsModule.cs

@@ -0,0 +1,20 @@
+using Examples.Bootstrapping.MultiModule.Producers;
+using Microsoft.Extensions.DependencyInjection;
+using RCommon;
+using RCommon.EventHandling;
+
+namespace Examples.Bootstrapping.MultiModule.Modules;
+
+/// <summary>
+/// The Notifications module re-registers <see cref="AuditProducer"/> (already registered by
+/// <see cref="OrderingModule"/>). The bootstrapper detects the duplicate and keeps a single
+/// descriptor, so <c>IServiceProvider.GetServices&lt;IEventProducer&gt;()</c> resolves it once.
+/// </summary>
+public class NotificationsModule : IServiceModule
+{
+    public void Configure(IServiceCollection services)
+    {
+        services.AddRCommon()
+            .WithEventHandling<InMemoryEventBusBuilder>(eh => eh.AddProducer<AuditProducer>());
+    }
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Modules/OrderingModule.cs

@@ -0,0 +1,26 @@
+using Examples.Bootstrapping.MultiModule.Data;
+using Examples.Bootstrapping.MultiModule.Producers;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.DependencyInjection;
+using RCommon;
+using RCommon.EventHandling;
+
+namespace Examples.Bootstrapping.MultiModule.Modules;
+
+/// <summary>
+/// The Ordering module configures persistence for its own DbContext and a guid generator,
+/// and registers an <see cref="AuditProducer"/> for cross-cutting auditing.
+/// </summary>
+public class OrderingModule : IServiceModule
+{
+    public void Configure(IServiceCollection services)
+    {
+        services.AddRCommon()
+            .WithSimpleGuidGenerator() // Singleton verb: idempotent across modules when impl matches.
+            .WithPersistence<EFCorePerisistenceBuilder>(ef =>
+                ef.AddDbContext<OrderingDbContext>(
+                    "Ordering",
+                    o => o.UseInMemoryDatabase("ordering")))
+            .WithEventHandling<InMemoryEventBusBuilder>(eh => eh.AddProducer<AuditProducer>());
+    }
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Producers/AuditProducer.cs

@@ -0,0 +1,18 @@
+using RCommon.EventHandling.Producers;
+using RCommon.Models.Events;
+
+namespace Examples.Bootstrapping.MultiModule.Producers;
+
+/// <summary>
+/// No-op <see cref="IEventProducer"/> used to demonstrate cross-module producer dedup.
+/// Two modules register this same producer type; the bootstrapper merges them into a single descriptor.
+/// </summary>
+public class AuditProducer : IEventProducer
+{
+    public Task ProduceEventAsync<TEvent>(TEvent @event, CancellationToken cancellationToken = default)
+        where TEvent : ISerializableEvent
+    {
+        // No-op for example purposes.
+        return Task.CompletedTask;
+    }
+}

Examples/Bootstrapping/Examples.Bootstrapping.MultiModule/Program.cs

@@ -0,0 +1,46 @@
+using Examples.Bootstrapping.MultiModule.Modules;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using RCommon;
+using RCommon.EventHandling.Producers;
+
+var host = Host.CreateDefaultBuilder(args)
+    .ConfigureServices(services =>
+    {
+        IServiceModule[] modules =
+        {
+            new OrderingModule(),
+            new InventoryModule(),
+            new NotificationsModule(),
+        };
+
+        Console.WriteLine($"IsRCommonInitialized before any module: {services.IsRCommonInitialized()}");
+
+        foreach (var module in modules)
+        {
+            module.Configure(services);
+            Console.WriteLine($"  {module.GetType().Name} configured; IsRCommonInitialized={services.IsRCommonInitialized()}");
+        }
+    })
+    .Build();
+
+await host.StartAsync();
+
+var sp = host.Services;
+var producerCount = sp.GetServices<IEventProducer>().Count();
+Console.WriteLine($"\nDistinct IEventProducer instances resolved: {producerCount}");
+Console.WriteLine("Expected: 1 (AuditProducer was registered by Ordering and Notifications but dedup keeps it to one).\n");
+
+var builder = sp.GetRequiredService<IRCommonBuilder>();
+var diagnostics = builder.GetBootstrapDiagnostics();
+if (!string.IsNullOrEmpty(diagnostics))
+{
+    Console.WriteLine("Bootstrap diagnostics report:");
+    Console.WriteLine(diagnostics);
+}
+else
+{
+    Console.WriteLine("Bootstrap diagnostics: no soft duplicates detected.");
+}
+
+await host.StopAsync();

Examples/Examples.sln

@@ -121,6 +121,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RCommon.TestBase", "..\Test
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Examples.Messaging.SubscriptionIsolation", "Messaging\Examples.Messaging.SubscriptionIsolation\Examples.Messaging.SubscriptionIsolation.csproj", "{DFF5FC1F-D20F-4BFE-BD58-A0B4F1E414CB}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Bootstrapping", "Bootstrapping", "{173CBA2D-76A2-457F-947A-8CBE38D63121}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Examples.Bootstrapping.MultiModule", "Bootstrapping\Examples.Bootstrapping.MultiModule\Examples.Bootstrapping.MultiModule.csproj", "{60782FC7-AB13-44D9-A4F1-E8C602697C3E}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -719,6 +723,18 @@ Global
 		{DFF5FC1F-D20F-4BFE-BD58-A0B4F1E414CB}.Release|x64.Build.0 = Release|Any CPU
 		{DFF5FC1F-D20F-4BFE-BD58-A0B4F1E414CB}.Release|x86.ActiveCfg = Release|Any CPU
 		{DFF5FC1F-D20F-4BFE-BD58-A0B4F1E414CB}.Release|x86.Build.0 = Release|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Debug|x64.Build.0 = Debug|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Debug|x86.Build.0 = Debug|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Release|Any CPU.Build.0 = Release|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Release|x64.ActiveCfg = Release|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Release|x64.Build.0 = Release|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Release|x86.ActiveCfg = Release|Any CPU
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -768,6 +784,8 @@ Global
 		{43AD4063-F157-994B-5A6D-92B9ABCA126E} = {3234C3BB-1632-4684-838E-9D6D382D4D4D}
 		{740F4266-7ADA-7893-C575-B8C531C029EC} = {3234C3BB-1632-4684-838E-9D6D382D4D4D}
 		{DFF5FC1F-D20F-4BFE-BD58-A0B4F1E414CB} = {35AE0870-0A6D-4F27-B534-B8DCDFD11A36}
+		{173CBA2D-76A2-457F-947A-8CBE38D63121} = {3234C3BB-1632-4684-838E-9D6D382D4D4D}
+		{60782FC7-AB13-44D9-A4F1-E8C602697C3E} = {173CBA2D-76A2-457F-947A-8CBE38D63121}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {0B0CD26D-8067-4667-863E-6B0EE7EDAA42}

Src/RCommon.ApplicationServices/CqrsBuilderExtensions.cs

@@ -50,7 +50,7 @@ public static class CqrsBuilderExtensions
         /// <param name="builder">The RCommon builder.</param>
         /// <returns>The <paramref name="builder"/> for further chaining.</returns>
         public static IRCommonBuilder WithCQRS<T>(this IRCommonBuilder builder)
-            where T : ICqrsBuilder
+            where T : class, ICqrsBuilder
         {
 
             return WithCQRS<T>(builder, x => { });
@@ -64,11 +64,13 @@ public static IRCommonBuilder WithCQRS<T>(this IRCommonBuilder builder)
         /// <param name="actions">A delegate to configure the CQRS builder (e.g., register handlers).</param>
         /// <returns>The <paramref name="builder"/> for further chaining.</returns>
         public static IRCommonBuilder WithCQRS<T>(this IRCommonBuilder builder, Action<T> actions)
-            where T : ICqrsBuilder
+            where T : class, ICqrsBuilder
         {
 
-            // Instantiate the CQRS builder implementation, which registers core bus services in its constructor
-            var cqrsBuilder = (T)Activator.CreateInstance(typeof(T), new object[] { builder })!;
+            // Instantiate the CQRS builder implementation, which registers core bus services in its constructor.
+            // Routed through GetOrAddBuilder so repeated WithCQRS<T> calls reuse the cached sub-builder.
+            var cqrsBuilder = builder.GetOrAddBuilder<T>(
+                () => (T)Activator.CreateInstance(typeof(T), new object[] { builder })!);
             actions(cqrsBuilder);
             return builder;
         }

Src/RCommon.ApplicationServices/ValidationBuilderExtensions.cs

@@ -23,7 +23,7 @@ public static class ValidationBuilderExtensions
         /// <param name="builder">The RCommon builder.</param>
         /// <returns>The <paramref name="builder"/> for further chaining.</returns>
         public static IRCommonBuilder WithValidation<T>(this IRCommonBuilder builder)
-            where T : IValidationBuilder
+            where T : class, IValidationBuilder
         {
             return WithValidation<T>(builder, x => { });
         }
@@ -36,14 +36,16 @@ public static IRCommonBuilder WithValidation<T>(this IRCommonBuilder builder)
         /// <param name="actions">A delegate to configure the validation builder (e.g., register validation providers).</param>
         /// <returns>The <paramref name="builder"/> for further chaining.</returns>
         public static IRCommonBuilder WithValidation<T>(this IRCommonBuilder builder, Action<T> actions)
-            where T : IValidationBuilder
+            where T : class, IValidationBuilder
         {
 
             builder.Services.AddScoped<IValidationService, ValidationService>();
 
-            // Instantiate the validation builder implementation, which may register provider-specific services
-            var mediatorConfig = (T)Activator.CreateInstance(typeof(T), new object[] { builder })!;
-            actions(mediatorConfig);
+            // Instantiate the validation builder implementation, which may register provider-specific services.
+            // Routed through GetOrAddBuilder so repeated WithValidation<T> calls reuse the cached sub-builder.
+            var validationConfig = builder.GetOrAddBuilder<T>(
+                () => (T)Activator.CreateInstance(typeof(T), new object[] { builder })!);
+            actions(validationConfig);
             return builder;
         }
 

Src/RCommon.Blobs/BlobStorageBuilderExtensions.cs

@@ -12,7 +12,7 @@ public static class BlobStorageBuilderExtensions
     /// Registers a blob storage provider with default configuration.
     /// </summary>
     public static IRCommonBuilder WithBlobStorage<T>(this IRCommonBuilder builder)
-        where T : IBlobStorageBuilder
+        where T : class, IBlobStorageBuilder
     {
         return WithBlobStorage<T>(builder, x => { });
     }
@@ -22,14 +22,17 @@ public static IRCommonBuilder WithBlobStorage<T>(this IRCommonBuilder builder)
     /// Can be called multiple times to register multiple providers (e.g. Azure + S3).
     /// </summary>
     public static IRCommonBuilder WithBlobStorage<T>(this IRCommonBuilder builder, Action<T> actions)
-        where T : IBlobStorageBuilder
+        where T : class, IBlobStorageBuilder
     {
         Guard.IsNotNull(actions, nameof(actions));
 
         builder.Services.TryAddSingleton<IBlobStoreFactory, BlobStoreFactory>();
 
-        var blobConfig = (T)(Activator.CreateInstance(typeof(T), new object[] { builder })
-            ?? throw new InvalidOperationException($"Failed to create instance of {typeof(T).Name}."));
+        // Routed through GetOrAddBuilder so repeated WithBlobStorage<T> calls for the same provider type
+        // reuse the cached sub-builder. Different T (e.g. Azure vs S3) still get distinct sub-builders.
+        var blobConfig = builder.GetOrAddBuilder<T>(
+            () => (T)(Activator.CreateInstance(typeof(T), new object[] { builder })
+                ?? throw new InvalidOperationException($"Failed to create instance of {typeof(T).Name}.")));
         actions(blobConfig);
         return builder;
     }